Commit Graph

10 Commits

Author SHA1 Message Date
9f4d2fb5f7 fix(PendingRequestMap): resolve type name conflict between env.ts interface and call.ts class
- Remove PendingRequestMap interface from env.ts (had reduced signature missing deadline, identity typed as unknown)
- Add CallMap interface in env.ts with full call() signature matching the class
- Update EnvOptions.callMap to use CallMap type
- Export PendingRequestMap class directly (remove PendingRequestMapClass alias)
- Export CallMap type from index.ts instead of old PendingRequestMap interface
2026-05-11 01:54:04 +00:00
b6c2b2c186 Add ADR-006 unified invocation path and source-vs-spec drift tables
ADR-006: Unify on registry.execute() as the single invocation entry point.
Call protocol becomes internal transport for cross-process routing.
CallHandler calls execute() instead of reimplementing lookup/validation.
Access control enforcement in execute() with trusted flag for nested calls.
Default-deny: reject when requiredScopes non-empty and identity absent.

Source-vs-spec drift tables added to call-protocol.md and api-surface.md,
documenting all gaps between architecture docs and current source:
- ADR-005 gaps (envelope types, pipeline, factory functions)
- ADR-006 gaps (unified invocation, access control, CallHandler refactor)
- Two bugs: checkAccess() resource bypass when identity.resources is
  undefined, and PendingRequestMap type/class naming conflict
2026-05-10 09:30:22 +00:00
51f233582d Align call-protocol.md and api-surface.md with envelope model
Remove supersession note from response-envelopes.md — both dependent
docs now reflect the ResponseEnvelope system. Key changes:

- call-protocol.md: CallHandler wraps and publishes (not handlers),
  call.responded.output uses ResponseEnvelopeSchema, respond() enforces
  envelope guard, call() resolves ResponseEnvelope, subscribe() yields
  ResponseEnvelope, references shared result pipeline
- api-surface.md: execute() returns Promise<ResponseEnvelope<TOutput>>,
  OperationEnv functions return Promise<ResponseEnvelope>, CallHandler
  calls handler directly and applies shared pipeline, respond() requires
  ResponseEnvelope, added Response Envelope Types and Utilities sections
- response-envelopes.md: removed supersession note, added Shared Result
  Pipeline section (detect→wrap→normalize→validate), unified execute()
  and CallHandler integration points to reference shared pipeline,
  updated migration checklist to mark doc changes complete
2026-05-10 08:37:40 +00:00
81f89e0f6c Restructure response envelopes architecture: split ADR from spec, add Value.Cast composability, document implementation gaps
- Split monolithic 680-line response-envelopes.md into focused ADR-005
  (decisions/005-response-envelopes.md, 152 lines) and specification
  (response-envelopes.md, 441 lines)
- ADR-005: consolidate 10 inline ADRs into coherent decision record with
  rationale for data+meta envelope shape, handler responsibility shift,
  string discriminant detection, and composability analysis
- Spec: types, factory functions, integration points, constraints, migration
  checklist, and open questions
- Add MCP outputSchema extraction (2025-06-18+ spec) with FromSchema
  conversion and<Value.Cast()> normalization for structuredContent
- Add current-source-vs-spec implementation gap tables to registry, call,
  mcp adapter, and openapi adapter integration points
- Update adapters.md: from_mcp outputSchema extraction, structuredContent
  handling, isError non-throw behavior, Value.Cast() for data normalization
- Add open questions: serving directionality, JSON.stringify in MCP content,
  outputSchema extraction completeness, respond() visibility
- Note: existing call-protocol.md and api-surface.md describe pre-envelope
  behavior; this spec supersedes them until updated per migration checklist
2026-05-10 07:56:27 +00:00
a7e6cc94c7 Add response envelopes architecture spec (ADR-005 through ADR-014)
Introduce ResponseEnvelope as a first-class concept for uniform operation
result handling across MCP, OpenAPI, and local adapters. Key decisions:

- ResponseEnvelope<T> wraps every result with typed metadata
  (LocalResponseMeta, HTTPResponseMeta, MCPResponseMeta)
- CallHandler becomes sole publisher of call.responded (handler
  responsibility shift from publish-to-return)
- Envelope detection via closed-set string discriminant
  (isResponseEnvelope) — no Symbols, JSON-serializable
- MCP isError:true no longer throws; wraps in envelope with
  meta.isError flag preserving error content for consumers
- outputSchema validates envelope.data, not the full envelope
- PendingRequestMap.respond() validates envelope at runtime
- Factory functions (localEnvelope, httpEnvelope, mcpEnvelope)
  ensure consistent construction
- Breaking change: execute() returns ResponseEnvelope<TOutput>,
  call.responded.output is ResponseEnvelopeSchema
- No Client abstraction yet (ADR-014)
2026-05-10 04:58:05 +00:00
d0017df2bf Update architecture docs for handler separation and pubsub API changes
- api-surface.md: Updated registry API table (registerSpec, registerHandler,
  getHandler, separated spec/handler storage), OperationSpec description,
  IOperationDefinition marked as convenience type, adapter return types
- call-protocol.md: Added pubsub EventEnvelope unwrapping details,
  subscribe(type, id) 2-arg API, handler separation in buildCallHandler
  and subscribe(), handler separation section
- adapters.md: Updated return types (OperationSpec & { handler }),
  scanner validates against OperationSpecSchema, new module shape examples
  showing spec-only and spec+handler patterns, typemap mention
- README.md: Core principle updated for spec/handler separation
- build-distribution.md: Updated pubsub dep description, registry.ts description
- AGENTS.md: Updated key points, source layout, provenance status
2026-05-09 08:34:41 +00:00
4f11f8e7a0 Separate handler from spec in OperationRegistry, update pubsub API
- Split OperationRegistry into separate specs and handlers maps
- Add registerSpec(), registerHandler(), getHandler() methods
- register() still accepts IOperationDefinition (backward compatible)
- execute() now requires both spec and handler, throws if missing
- Update @alkdev/pubsub integration for v0.1.0 API:
  - subscribe(type, id) now requires id parameter (use  for all events)
  - publish(type, id, payload) now requires 3 args
  - Events unwrapped from EventEnvelope via .payload
- Update buildCallHandler to use getSpec() + getHandler() separately
- Update subscribe.ts to use getHandler()
- Update buildEnv to use getAllSpecs() instead of list()
- Update scanner to validate against OperationSpecSchema
- Update from_mcp and from_openapi to use OperationSpec & { handler } types
- Remove OperationDefinitionSchema from public exports
- Add 7 new registry tests for handler separation
2026-05-09 08:25:59 +00:00
c5979ecd63 added agent defs 2026-05-08 18:09:02 +00:00
29f0dd7af0 Initial package implementation: operations registry, call protocol, and adapters
Extracted from alkhub_ts packages/core/operations/ and packages/core/mcp/.
- Runtime-agnostic (injected fs/env deps, no Deno globals)
- Direct @logtape/logtape import instead of logger wrapper
- PendingRequestMap with pubsub-wired call protocol
- Peer-dep isolation for MCP adapter (sub-path export)
- Schema const naming convention (XSchema + X type alias)
- 68 tests passing, build + lint + test all green
2026-04-30 12:34:26 +00:00
9c41f683ee init 2026-04-30 09:39:35 +00:00