Merged
Conversation
- Add VulnerabilityRecord Pydantic model with required name field and optional aliases and url fields (CM-05-001, CM-05-008, CM-05-009) - Add CaseReference Pydantic model with required url field and optional name and tags fields aligned with CVE JSON schema vocabulary (CM-05-001, CM-05-005) - Update VultronObjectType enum to include VULNERABILITY_RECORD and CASE_REFERENCE - Add comprehensive test suites for both models - All 623 existing tests still pass; added 31 new tests (11 for VulnerabilityRecord, 20 for CaseReference) - Update IMPLEMENTATION_PLAN.md to mark SC-1.1 and SC-1.2 as complete - Update IMPLEMENTATION_NOTES.md with implementation details Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…in create_case BT (CM-02-008) - Add SetCaseAttributedTo node: sets case.attributed_to to actor_id before persisting so the stored VulnerabilityCase carries the vendor/owner reference - Add CreateInitialVendorParticipant node: creates and persists a VendorParticipant linked to the case, then appends it to case.case_participants (idempotent) - Update CreateCaseBT sequence to include both new nodes in correct order - Add tests: test_create_case_tree_sets_attributed_to and test_create_case_tree_creates_vendor_participant - Update initialize_participant_demo to remove redundant explicit vendor participant creation (BT now handles it per CM-02-008) 625 passed, 5581 subtests passed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add EMBARGO_POLICY to VultronObjectType enum - Create EmbargoPolicy VultronObject with required actor_id, inbox, preferred_duration_days and optional min/max duration and notes fields - Validators reject empty strings for actor_id, inbox, notes (CS-08-001) - ge=0 constraint on all duration integer fields - EmbargoPolicyRef TypeAlias for ActivityStreamRef usage - 24 unit tests: creation, required/optional fields, validators, object_to_record round-trip, DataLayer persistence, JSON serialization 649 passed, 5581 subtests passed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…rvice subclasses Add optional embargo_policy field to actor profile models via a shared mixin, implementing specs/embargo-policy.md EP-01-001. - VultronActorMixin(BaseModel): single source of embargo_policy field - VultronPerson(VultronActorMixin, as_Person): preserves as_type='Person' - VultronOrganization(VultronActorMixin, as_Organization): preserves as_type='Organization' - VultronService(VultronActorMixin, as_Service): preserves as_type='Service' All three concrete classes are registered via @activitystreams_object. 16 new unit tests; full suite 665 passed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…closurePolicy and DIOSTS format
… CM-10-003) Add `accepted_embargo_ids: list[str]` field to `CaseParticipant` to track which embargo(es) a participant has explicitly accepted, per specs/case-management.md CM-10-001 and CM-10-003. - Field defaults to empty list - Inherited by all CaseParticipant subclasses - Survives JSON and object_to_record/record_to_object round-trips - 9 new unit tests in test/as_vocab/test_case_participant.py Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
SC-3.2 (record accepted embargo ID with trusted timestamp) requires: - SC-PRE-1: CaseEvent model + append-only event log on VulnerabilityCase for server-generated trusted timestamps (CM-02-009, CM-10-002) - SC-PRE-2: actor-to-participant index on VulnerabilityCase with add_participant() / remove_participant() methods for safe actor ID resolution within a case More than one prerequisite required; implementation deferred per BUILD_prompt rules. Design notes added to IMPLEMENTATION_NOTES.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…urePolicy in notes/ - notes/case-state-model.md: add trusted-timestamp implementation note (do NOT modify updated_at; use append-only event log); add CaseEvent model design (SC-PRE-1); add actor-to-participant index design (SC-PRE-2) - notes/do-work-behaviors.md: add future VulnerabilityDisclosurePolicy wrapper object design note (DIOSTS/security.txt analogy, deferred) - notes/domain-model-separation.md: add MongoDB community edition as the recommended production path for per-actor DataLayer isolation (from IDEAS.md) - notes/README.md: update topic summaries to reflect new sections - specs/README.md: update implementation status summary (665 tests, object model gaps closed: SC-1.1/SC-1.2/SC-1.3, EP-1.1/EP-1.2 complete) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
plan/IDEAS.md:
- Mark MongoDB/TinyDB replacement note as captured in
notes/domain-model-separation.md (strikethrough + reference)
plan/IMPLEMENTATION_NOTES.md:
- Mark SC-PRE-1/SC-PRE-2 design prerequisites as captured in
notes/case-state-model.md
- Mark VulnerabilityDisclosurePolicy design note as captured in
notes/do-work-behaviors.md
- Mark Timestamp notes as captured in notes/case-state-model.md
- Mark participant-to-actor index note as captured in
notes/case-state-model.md and AGENTS.md
- Clean up DIOSTS JSON example (already captured in notes)
plan/IMPLEMENTATION_PLAN.md (gap analysis refresh #14):
- Update test count: 592 → 665
- Mark SC-1.1/SC-1.2 (CM-05-001) gap as ✅ resolved
- Mark SC-1.3 (CM-02-008) gap as ✅ resolved
- Mark EP-01 (embargo policy model) gap as ✅ resolved
- Update CM-10 spec compliance from ❌ to ⚠️ partial
- Update ACT-1 to mention MongoDB as recommended production path
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Update test count: 665 → 674 (reflects EP-1.1, EP-1.2, SC-1.3, SC-3.1) - Fix stale CM-10 gap analysis text (SC-3.1 accepted_embargo_ids now done) - Add vultron-protocol-spec.md VP-level gap note (~40 untracked reqs) - Update EP-1.2 task note to remove stale test count - Add refresh #15 entry to IMPLEMENTATION_NOTES.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nd-only log - Add CaseEvent plain Pydantic model in vultron/as_vocab/objects/case_event.py with object_id, event_type, received_at (TZ-aware UTC) fields - Add events: list[CaseEvent] field to VulnerabilityCase - Add record_event() helper that sets server-generated trusted timestamp - Add 19 tests in test/as_vocab/test_case_event.py covering creation, validation, serialization, and datalayer round-trip - 693 tests pass (up from 674) Per specs/case-management.md CM-02-009, CM-10-002. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…kfill task, AGENTS pitfall - plan/IMPLEMENTATION_PLAN.md: bump to gap analysis refresh #17; mark SC-PRE-1 complete in gap analysis and CM-10/CM-02-009 rows; update Spec Compliance table; add TECHDEBT-9 (NonEmptyString type alias per CS-08-002) and TECHDEBT-10 (backfill pre-case events) - specs/code-style.md: add CS-08-002 requiring NonEmptyString type alias to consolidate per-field empty-string validators (from plan/IDEAS.md) - notes/case-state-model.md: update CaseEvent section to reflect SC-PRE-1 is implemented; add record_event() API note and remaining-work callout - AGENTS.md: update CS-08-001 guidance to reference CS-08-002 and NonEmptyString type alias; add CaseEvent trusted-timestamp pitfall; add case_event.py to Key Files Map - plan/IMPLEMENTATION_NOTES.md: reset — all completed items promoted to notes/ and plan/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create vultron/api/v2/routers/triggers.py with ValidateReportRequest Pydantic model (extra='ignore' per TB-03-002) and trigger_validate_report endpoint (TB-01-001, TB-01-002, TB-03-001, TB-03-002, TB-03-003, TB-04-001, TB-05-001, TB-05-002, TB-06-001, TB-06-002, TB-07-001) - Register triggers router in v2_router.py - Add 9 tests in test/api/v2/routers/test_triggers.py covering: 202 response, activity key in body, 422 on missing offer_id, unknown fields ignored, structured 404 for unknown actor/offer, optional note field, DI via Depends, outbox mutation verified - Update IMPLEMENTATION_PLAN.md: mark P30-1 done, update test count (702), update gap analysis to reflect partial progress on PRIORITY 30 - Update IMPLEMENTATION_NOTES.md with P30-1 outbox-diff strategy note 702 tests pass (was 693). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ints (P30-2)
Add POST /actors/{actor_id}/trigger/invalidate-report and
POST /actors/{actor_id}/trigger/reject-report endpoints to
vultron/api/v2/routers/triggers.py.
invalidate-report emits RmInvalidateReport (TentativeReject(Offer(Report))),
updates offer status to TENTATIVELY_REJECTED and report status to INVALID,
and adds the activity to the actor's outbox.
reject-report emits RmCloseReport (Reject(Offer(Report))), requires a non-empty
note field (TB-03-004; empty note logs WARNING), updates offer status to
REJECTED and report status to CLOSED, and adds the activity to the actor's
outbox.
Both endpoints return HTTP 202 with {"activity": {...}} per TB-04-001.
A shared _add_activity_to_outbox() helper DRYs up the outbox append pattern.
Implements: TB-01-001, TB-01-002, TB-01-003, TB-02-001, TB-03-001,
TB-03-002, TB-03-003, TB-03-004, TB-04-001, TB-06-001,
TB-06-002, TB-07-001
17 new tests added; 719 tests pass (up from 702).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add POST /actors/{actor_id}/trigger/engage-case and
POST /actors/{actor_id}/trigger/defer-case endpoints to
vultron/api/v2/routers/triggers.py (TB-02-001, TB-03-001).
Both endpoints:
- Accept a CaseTriggerRequest body with case_id (TB-03-001, TB-03-002)
- Emit RmEngageCase (Join) or RmDeferCase (Ignore) activity
- Transition the local actor's CaseParticipant RM state to ACCEPTED/DEFERRED
- Add the activity to the actor's outbox (TB-07-001)
- Return HTTP 202 with {"activity": {...}} (TB-04-001)
- Return 404 for unknown actor or case (TB-01-003)
New helpers added: _resolve_case(), _update_participant_rm_state().
17 new tests in test_triggers.py; 736 tests pass.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…dapters architecture
- Create specs/architecture.md with hexagonal architecture requirements (ARCH-01 to ARCH-08) derived from notes/architecture-ports-and-adapters.md - Add 4 new notes files to notes/README.md: architecture-ports-and-adapters.md, architecture-review.md, federation_ideas.md, demo-future-ideas.md - Fix TB prefix conflict: rename triggerable-behaviors.md requirements from TB- to TRIG-; add prefix registry table to specs/README.md; update external reference in notes/do-work-behaviors.md - Add TRIG-01-005: trigger endpoints are synchronous for the caller - Update plan/PRIORITIES.md Priority 300 to reference notes/demo-future-ideas.md instead of plan/IDEAS.md - Add forward reference to notes/federation_ideas.md from specs/prototype-shortcuts.md Federation section - Add Hexagonal Architecture section and trigger-logic decoupling guidance to AGENTS.md - Capture pre-case event backfill and multi-vendor CVD action rule design insights in notes/case-state-model.md - Fix notes/activitystreams-semantics.md ephemeral IMPLEMENTATION_NOTES reference; fix notes/domain-model-separation.md IDEAS.md reference - Mark captured items in plan/IDEAS.md and plan/IMPLEMENTATION_NOTES.md with strikethrough and capture references - Remove plan/IMPLEMENTATION_NOTES.md from specs/README.md Related Documentation (ephemeral file should not be referenced from specs) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ble-behaviors.md Add 'Resolved Design Decisions: Trigger Implementation (P30-1 through P30-3)' section covering: - P30-1: outbox-diff strategy for retrieving the resulting activity - P30-2: procedural implementation for invalidate-report and reject-report, including _add_activity_to_outbox() helper and reject-report note semantics - P30-3: procedural implementation for engage-case and defer-case, including _resolve_case() and _update_participant_rm_state() helpers - Request model DRY pattern guidance Also update the stale 'A formal spec SHOULD be drafted' note to reflect that specs/triggerable-behaviors.md now exists. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
specs/code-style.md: - Add CS-09-001: code reuse requirement (extract shared logic into helpers, check existing code before creating new) - Add CS-09-002: Pydantic request/response model reuse requirement for routers (subclass or alias instead of duplicating) AGENTS.md: - Add triggers.py to Key Files Map - Add 'Reuse request/response models before creating new ones' guidance referencing CS-09-002 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…TES.md IDEAS.md: - Mark 'Backfill pre-case events' as captured → notes/case-state-model.md - Mark 'Case state action rules' as captured → notes/case-state-model.md IMPLEMENTATION_NOTES.md: - Mark P30-1 outbox-diff → notes/triggerable-behaviors.md - Mark Black format guidance → AGENTS.md (already present) - Mark DRY code → specs/code-style.md CS-09-001/CS-09-002, AGENTS.md - Mark P30-2 procedural triggers → notes/triggerable-behaviors.md - Mark DRY router models → specs/code-style.md CS-09-002, AGENTS.md - Mark P30-3 procedural case triggers → notes/triggerable-behaviors.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Correct test count: 665 → 736 - Update triggerable behaviors status: not-started → P30-1–P30-3 complete (validate-report, invalidate-report, reject-report, engage-case, defer-case) - Update summary date to 2026-03-09 - Remove SC from prefix registry (SC-N.N is a plan task identifier in IMPLEMENTATION_PLAN.md, not a spec requirement prefix) - Expand code-style.md description to mention CS-09-001 (code reuse) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…tation bugs in IDEAS.md and IMPLEMENTATION_NOTES.md
…leted work, trim plan to 308 lines
- Archive to IMPLEMENTATION_HISTORY.md: BUGFIX-1, REFACTOR-1, TECHDEBT-1/5/6,
SPEC-COMPLIANCE-1, SPEC-COMPLIANCE-2, SC-3.1, SC-PRE-1, P30-1/2/3
- Rewrite IMPLEMENTATION_PLAN.md: 633 → 308 lines; forward-looking only
- Add Phase ARCH-1 (PRIORITY 150): ARCH-1.1/1.2/1.3/1.4 correspond to
remediation steps R-01 through R-06 in notes/architecture-review.md
- Gap analysis updated: ARCH violations, SC-PRE-2/SC-3.2/SC-3.3 status,
P30-4/5/6 remaining, TECHDEBT-7/8/9/10 outstanding
- Update IMPLEMENTATION_NOTES.md: architecture violation notes, P30-4 vs
reject-report distinction, CS-09-002 triggers.py duplication note
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Implements POST /actors/{actor_id}/trigger/close-report (TB-02-001).
Emits RmCloseReport (Reject(Offer(VulnerabilityReport))) for the RM
lifecycle closure transition; updates offer/report status and actor
outbox. Returns HTTP 409 if the report is already CLOSED.
Also converts RM enum from plain Enum to StrEnum for consistency with
the existing EM(StrEnum). This makes str(RM.X) == X.value (e.g.,
'CLOSED' instead of 'RM.REPORT_MANAGEMENT_CLOSED'), resulting in
cleaner BT node names. Updates test_conditions.py to assert
state.value in node.name instead of state.name.
Adds 9 unit tests covering: HTTP 202 happy path, activity key in
response, missing offer_id 422, unknown fields ignored, optional note,
unknown actor 404, unknown offer 404, outbox updated, and 409 when
already CLOSED.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…gerable behaviors
… to align with hexagonal architecture
…agonal architecture
Add three embargo management trigger endpoints to the API:
- POST /{actor_id}/trigger/propose-embargo
- POST /{actor_id}/trigger/evaluate-embargo
- POST /{actor_id}/trigger/terminate-embargo
Each endpoint follows existing trigger patterns (procedural logic in
router, HTTP 202 with activity in response body) and implements the
state transitions defined in the EM protocol:
- propose-embargo: N→P or A→R, emits EmProposeEmbargo (Invite)
- evaluate-embargo: accepts a proposal, EM→ACTIVE, emits EmAcceptEmbargo
- terminate-embargo: EM→EXITED, clears active_embargo, emits AnnounceEmbargo
Key implementation notes:
- dl.read() reconstructs objects as their registered vocabulary class
(e.g., EmProposeEmbargo → as_Invite, EmbargoEvent → as_Event), so
type checks use str(obj.as_type) comparisons rather than isinstance()
- rehydrate() uses the singleton DataLayer (not DI-injected), so
embargo resolution uses dl.read() directly with the injected instance
- _find_embargo_proposal() scans by_type('Invite') and validates the
object is an Event-type to distinguish from actor invites
Adds 31 new tests covering all three endpoints.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add `vultron-demo trigger` sub-command demonstrating actor-initiated (proactive) trigger endpoint workflows end-to-end. Changes: - vultron/demo/trigger_demo.py: new demo script with two workflows: 1. validate-report → engage-case (happy path) 2. invalidate-report → close-report (invalid report path) - vultron/demo/utils.py: add post_to_trigger() helper - vultron/demo/cli.py: add 'trigger' to DEMOS list - docs/reference/code/demo/demos.md: add trigger demo section - docs/reference/code/demo/cli.md: add trigger to usage examples - plan/IMPLEMENTATION_PLAN.md: mark P30-6 complete - plan/IMPLEMENTATION_NOTES.md: document P30-6 implementation Closes Phase PRIORITY-30 (all of P30-1 through P30-6 are now complete). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds triggerable (actor-initiated) behavior endpoints and supporting demos/models, while formalizing the project’s shift toward a hexagonal (ports/adapters) architecture and tightening specification + guidance around validation, reuse, and event logging.
Changes:
- Introduces trigger demo command + helper utilities to exercise
POST /actors/{id}/trigger/{behavior}workflows end-to-end. - Expands ActivityStreams vocabulary/object model support (e.g.,
VulnerabilityRecord,CaseReference,EmbargoPolicy, Vultron-extended actors) and adds trusted-timestamp case event logging (CaseEvent+record_event()). - Updates behavior-tree case creation flow to set case ownership and auto-create the initial vendor participant (CM-02-008), with corresponding tests and architecture/spec documentation.
Reviewed changes
Copilot reviewed 52 out of 52 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| vultron/enums.py | Extends Vultron object type enum. |
| vultron/demo/utils.py | Adds post_to_trigger() helper. |
| vultron/demo/trigger_demo.py | New trigger endpoint demo workflow. |
| vultron/demo/initialize_participant_demo.py | Removes manual vendor participant creation. |
| vultron/demo/cli.py | Registers trigger demo command. |
| vultron/bt/report_management/states.py | Converts RM enum to StrEnum. |
| vultron/behaviors/case/nodes.py | Adds case owner + initial vendor participant nodes. |
| vultron/behaviors/case/create_tree.py | Wires new nodes into CreateCase BT. |
| vultron/as_vocab/objects/vultron_actor.py | New Vultron-extended actor types/mixin. |
| vultron/as_vocab/objects/vulnerability_record.py | New VulnerabilityRecord model + example emitter. |
| vultron/as_vocab/objects/vulnerability_case.py | Adds events + record_event() helper. |
| vultron/as_vocab/objects/embargo_policy.py | New EmbargoPolicy model + example emitter. |
| vultron/as_vocab/objects/case_reference.py | New CaseReference model + CVE tag vocabulary constant. |
| vultron/as_vocab/objects/case_participant.py | Adds accepted_embargo_ids field. |
| vultron/as_vocab/objects/case_event.py | New trusted-timestamp CaseEvent model. |
| vultron/api/v2/routers/v2_router.py | Includes triggers router in v2 API. |
| test/bt/test_report_management/test_conditions.py | Updates expectation for RM StrEnum naming. |
| test/behaviors/case/test_create_tree.py | Tests case attributed_to + vendor participant creation. |
| test/as_vocab/test_vultron_actor.py | Tests Vultron actor mixin + policy embedding. |
| test/as_vocab/test_vulnerability_record.py | Tests VulnerabilityRecord validation/round-trips. |
| test/as_vocab/test_embargo_policy.py | Tests EmbargoPolicy validation/round-trips. |
| test/as_vocab/test_case_reference.py | Tests CaseReference validation/round-trips. |
| test/as_vocab/test_case_participant.py | Tests accepted_embargo_ids serialization. |
| test/as_vocab/test_case_event.py | Tests CaseEvent + VulnerabilityCase.events. |
| specs/triggerable-behaviors.md | Renames prefix to TRIG-* and refines trigger semantics. |
| specs/prototype-shortcuts.md | Adds federation-model note for prototype context. |
| specs/code-style.md | Adds CS-08-002 and CS-09 reuse guidance. |
| specs/architecture.md | New formal hexagonal architecture spec (ARCH-*). |
| specs/README.md | Registers new specs + prefix registry updates. |
| prompts/LEARN_prompt.md | Updates plan filename reference to plan/IDEAS.md. |
| prompts/LEARN_EXTRA_prompt.md | Fixes/clarifies documentation study instructions. |
| prompts/IDEATION_prompt.md | Updates ideation prompt references (path issue noted). |
| plan/PRIORITIES.md | Adds Priority 50 architecture shift + updates demo notes. |
| plan/IMPLEMENTATION_PLAN.md | Refreshes status, moves/records completed P30 items. |
| plan/IMPLEMENTATION_NOTES.md | Captures architecture inventory + P30 completion notes. |
| plan/IMPLEMENTATION_HISTORY.md | Records completed phases (SC/EP/P30/etc.). |
| plan/IDEAS.md | Updates ideas list (adds MCP-related idea). |
| notes/triggerable-behaviors.md | Links to formal TRIG spec + captures design decisions. |
| notes/federation_ideas.md | New federation design exploration notes. |
| notes/domain-model-separation.md | Adds MongoDB production-path guidance + DI note. |
| notes/do-work-behaviors.md | Updates TRIG reference + adds future policy wrapper idea. |
| notes/demo-future-ideas.md | New multi-actor demo scenario sketches. |
| notes/case-state-model.md | Documents CaseEvent model + remaining work. |
| notes/architecture-review.md | New violation inventory + remediation plan. |
| notes/architecture-ports-and-adapters.md | New ports/adapters architecture design note. |
| notes/activitystreams-semantics.md | Fixes reference target. |
| notes/README.md | Indexes new/updated notes. |
| docs/reference/code/demo/demos.md | Adds trigger demo doc stub. |
| docs/reference/code/demo/cli.md | Adds vultron-demo trigger to CLI docs. |
| AGENTS.md | Adds hex architecture guidance + validation/event logging rules. |
Contributor
Author
|
@copilot open a new pull request to apply changes based on the comments in this thread |
Contributor
|
@ahouseholder I've opened a new pull request, #320, to work on those changes. Once the pull request is ready, I'll request review from you. |
…bulary validation, ValueError masking, broken path Co-authored-by: ahouseholder <2594236+ahouseholder@users.noreply.github.com>
Fix review feedback: shared type aliases, Z timestamp, vocabulary validation, ValueError masking
Contributor
Author
|
Merged with a couple markdownlint errors, will catch them in the next PR. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR focuses on adding triggerable endpoints that will lay the foundation for local interactions with Vultron cases by human and system actions. In the course of the implementation, we found that there was an opportunity to improve our architectural clarity with the explicit adoption of a hexagonal (ports and adapters) architecture, which paves the way for future integration between Vultron and other systems.
This pull request primarily updates the documentation to clarify architectural patterns, coding standards, and demo behavior for the Vultron project. The most significant changes are the introduction and elaboration of the hexagonal architecture (Ports and Adapters), improvements to error handling and request/response model reuse guidance, and expanded demo documentation. These updates are aimed at making the codebase more maintainable and consistent, and at supporting future development by providing clear architectural direction.
Architectural Guidance and Documentation:
AGENTS.mdspecifying the adoption of Hexagonal Architecture (Ports and Adapters), including domain/core isolation rules, adapter patterns, and references to new architectural specification and review documents.notes/README.mdto reference new and expanded architectural documents, includingarchitecture-ports-and-adapters.md,architecture-review.md, and additional demo and federation design notes.Coding Standards and Error Handling:
AGENTS.mdto require the use of sharedNonEmptyStringorOptionalNonEmptyStringtype aliases for empty-string rejection, discouraging per-field validators, and referencing new code style rules.AGENTS.mdto reuse or subclass existing Pydantic request/response models before creating new ones, supporting maintainability and consistency.Behavior and Event Logging:
CaseEventtrusted-timestamp event logging approach inAGENTS.md, emphasizing the use ofrecord_event()and prohibiting copying timestamps from incoming activities.CaseEventmodel and event logging methods in the module overview section ofAGENTS.md.Demo and Triggerable Behavior Documentation:
triggerdemo command indocs/reference/code/demo/cli.mdanddocs/reference/code/demo/demos.md. [1] [2]AGENTS.mdto include triggerable behavior endpoints and their specification.Reference and Cross-linking Improvements:
notes/activitystreams-semantics.mdto point to the updated BT integration design document.