@stigmer/server 3.23.0 → 3.24.0

package/dist/pipeline/steps/references.d.ts

@@ -1,38 +1,222 @@
 /**
- * NormalizeReferences + ValidateReferences — port
- * steps/normalize_references.go and steps/validate_references.go, sharing
- * one spec walker (as the Go files share theirs).
+ * References — the two shared steps every chain that stores a spec with
+ * `ApiResourceReference` fields runs, and the ONE rule that decides whether
+ * a reference may be written.
  *
  * NormalizeReferences fills EMPTY org fields in ApiResourceReference
  * messages inside the spec from the resource's own metadata.org, so stored
- * references are absolute; explicit orgs (cross-org refs) are preserved.
- * Only the spec is walked — status is system-generated and already
- * absolute. Runs after BuildNewState/BuildUpdateState, before Persist.
- *
- * ValidateReferences verifies spec references point at existing resources
- * — strict FAILED_PRECONDITION for missing MCP servers (an agent whose MCP
- * server is missing cannot execute its declared tools). Runs AFTER
- * NormalizeReferences so orgs are resolved.
+ * references are absolute; an explicit org is preserved. Only the spec is
+ * walked — status is system-generated and already absolute. Runs after
+ * BuildNewState/BuildUpdateState, before Persist.
+ *
+ * ValidateReferences runs directly after it and asks `checkReference` for
+ * every reference the walk finds. The rule has three clauses, in the
+ * order they are asked:
+ *
+ *   (i)  A reference with no organization is refused. After the normalize
+ *        step the only way an org is still empty is a resource that has
+ *        none itself; a slug looked up with no org matches any
+ *        organization's row (helpers.ts), which is the cross-tenant read
+ *        the reference lane's `requireOrgForReference` exists to forbid.
+ *   (ii) Same organization as the resource: the target must exist, and,
+ *        when the target's kind is one the RUN reads as the person
+ *        (`readByRun` in the table below), its visibility must be at least
+ *        the resource's on the order private < org < platform — the FLOOR.
+ *        What a person can run they must also be able to read: an
+ *        org-visible agent over a private MCP server would run for every
+ *        member and be readable by one. Environments, OAuth apps and
+ *        channel apps are resolved by the server on the run's behalf and
+ *        never read by the person, so their level is not a leak the floor
+ *        closes, and an org-visible instance may hold a private personal
+ *        environment as it always has. A RELATIVE reference (below) is
+ *        compared against the resource's level capped at org.
+ *   (iii) Another organization: the target must exist AND be
+ *        platform-visible, answered with ONE sentence that does not say
+ *        which failed. The caller has no standing to learn what another
+ *        organization holds (the anti-probe posture the AgentShare lane set
+ *        first). The rule reads the target's LEVEL, not tenancy: whether
+ *        the writer's organization is one the target's identity provider
+ *        links is the run-time authorizer's question, asked when the run
+ *        reads the target, and the copy here claims no more than the rule
+ *        checks. No Environment, OAuth app or channel app is ever
+ *        platform-visible, so every cross-organization reference to one is
+ *        refused here.
+ *
+ * The kind a reference names is the kind its FIELD declares
+ * (`reference_kind`, the contract's word for what the field points to),
+ * never the `kind` value a client happened to put on the message: the
+ * runtime resolves `skill_refs` as skills whatever the message says, and
+ * the rule must agree with the runtime. A reference with an empty slug is
+ * unset and skipped (the field-level CEL rules own "required").
+ *
+ * A reference is RELATIVE when it names no organization of its own and
+ * the runtime resolves it in the organization the resource RUNS in, not
+ * the one it is stored in. Exactly one exists: a workflow `agent_call`
+ * task's bare slug (domain/workflow/agent-call-references.ts), which the
+ * runner resolves in the execution's organization; any workflow a person
+ * may execute can run from another organization by id. The rule judges
+ * it in the resource's own organization — the one its author can see, so
+ * the target must exist there — and caps its floor at org: only the
+ * running organization's own people ever read a target through it, and
+ * they can read an org-visible one. The cap changes nothing for a
+ * private or org resource and lets a platform-visible workflow call its
+ * organization's org-visible agent. A value fixed only at run (an
+ * `agent_call` agent holding a runtime expression) is not a reference at
+ * all: the collector yields nothing for it, and the run reads the
+ * resolved target as the person the run acts as, as it reads every
+ * id-bound binding.
+ *
+ * The floor has a second door. Raising a resource's level through
+ * updateVisibility could open the same gap a create cannot, so
+ * GuardReferenceFloorOnEscalation runs on the two chains whose rows carry
+ * run-read references (agent, workflow) after ValidateVisibilityUpdate:
+ * when the requested level is above the stored one, every run-read
+ * reference the STORED row carries must be at least the requested level
+ * (a relative one, at least the requested level capped at org), judged by
+ * the same function over the same collectors, else the escalation is
+ * refused naming the dependencies. Only the floor is asked at
+ * that door — a dependency that has since left or stopped being shared was
+ * judged when the row was written and is the run's to refuse.
+ *
+ * REFERENCE_TARGET_KINDS is the one explicit table of kinds a spec may
+ * reference, with each kind's schema and its `readByRun` flag: the
+ * composition-root idiom (query/search/registry.ts) — an explicit list a
+ * test pins against the protos, so a new `reference_kind` in the contract
+ * fails the pin until this table says how it is read.
+ *
+ * Cost: one `listResources` scan per referenced KIND per write (not per
+ * reference), decoded once into a (org, slug) index; the same scan every
+ * runtime path already pays per reference when it resolves the target at
+ * run start. A store read by (kind, org, slug) is the follow-on that
+ * removes the scan everywhere, and is not this module's.
+ *
+ * The refusal copy is exported below. The MCP-server sentence predates the
+ * rule and is wire contract (byte-pinned by pipeline/__tests__/steps.test.ts
+ * and the agent conformance suite); its siblings for the other kinds take
+ * the same shape. `collectSpecReferences` is the walk exported for the
+ * readers that ask the reverse question ("who references this?").
  */
-import type { DescMessage } from "@bufbuild/protobuf";
+import type { DescMessage, Message } from "@bufbuild/protobuf";
 import { reflect } from "@bufbuild/protobuf/reflect";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { Store } from "../../store/interface.js";
+import { failedPreconditionError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
-export declare function newNormalizeReferencesStep<Desc extends DescMessage>(): PipelineStep<Desc>;
-export declare function newValidateReferencesStep<Desc extends DescMessage>(store: Store): PipelineStep<Desc>;
-/** One reference a spec carries, as the walker reads it. */
+/** One kind a spec may reference, and how the rule reads it (the module header). */
+export interface ReferenceTargetKind {
+    readonly kind: ApiResourceKind;
+    readonly schema: DescMessage;
+    /** Whether the run reads the target AS THE PERSON — the kinds the floor applies to. */
+    readonly readByRun: boolean;
+    /** The kind in the refusal copy's words, singular with the plural marker: "MCP server(s)". */
+    readonly label: string;
+    /** The CLI command a refusal points at, or undefined where the CLI has no verb for the kind. */
+    readonly listHint: string | undefined;
+}
+export declare const REFERENCE_TARGET_KINDS: ReadonlyArray<ReferenceTargetKind>;
+export declare function referenceTargetKind(kind: ApiResourceKind): ReferenceTargetKind | undefined;
+/** One reference a spec carries, as the walker reads it; `kind` is the field's declared kind. */
 export interface SpecReference {
     readonly kind: ApiResourceKind;
     readonly slug: string;
     readonly org: string;
+    /**
+     * Present only on a RELATIVE reference (the module header): `org` is the
+     * resource's own, filled by the collector, and the runtime resolves the
+     * slug in the organization the resource runs in. The generic walker
+     * never sets it; only the `agent_call` collector does.
+     */
+    readonly resolvesIn?: "running-organization";
+}
+/** The resource the references belong to, as the rule needs it. */
+export interface ReferenceParent {
+    readonly org: string;
+    readonly visibility: ApiResourceVisibility;
+}
+/** What the rule found for one reference; the collectors turn it into copy. */
+export type ReferenceVerdict = {
+    readonly kind: "ok";
+}
+/** Clause (i): the reference names no organization. */
+ | {
+    readonly kind: "no-org";
 }
+/** Clause (ii): the same-organization target does not exist. */
+ | {
+    readonly kind: "missing";
+}
+/** Clause (ii): the target exists and is less visible than the resource. */
+ | {
+    readonly kind: "below-floor";
+    readonly targetVisibility: ApiResourceVisibility;
+}
+/** Clause (iii): the other-organization target is missing or not platform-visible — one answer. */
+ | {
+    readonly kind: "not-available";
+};
+/** The visibility of every referenced row the rule may need, one scan per kind (the module header). */
+export interface ReferenceTargets {
+    visibilityOf(ref: SpecReference): ApiResourceVisibility | undefined;
+}
+/**
+ * Loads the rows the given references could name: one `listResources` per
+ * distinct kind, decoded once, indexed by (org, slug). A row that does not
+ * decode is skipped as the slug helpers skip it — it is not a row a
+ * reference can reach. A reference whose kind is not in the table is a
+ * contract the pin test has not admitted yet and is an internal fault.
+ */
+export declare function loadReferenceTargets(store: Store, refs: ReadonlyArray<SpecReference>): Promise<ReferenceTargets>;
+/** The three clauses of the module header, for one reference. */
+export declare function checkReference(targets: ReferenceTargets, parent: ReferenceParent, ref: SpecReference): ReferenceVerdict;
+/** Clause (i)'s sentence. */
+export declare function noOrgReferenceMessage(entry: ReferenceTargetKind, slug: string): string;
+/**
+ * Clause (ii)'s sentence for the targets not found, one per kind. The MCP
+ * server form is the wire contract that predates the rule; the others are
+ * its siblings.
+ */
+export declare function missingReferencesMessage(entry: ReferenceTargetKind, handles: ReadonlyArray<{
+    readonly slug: string;
+    readonly org: string;
+}>): string;
+/** Clause (ii)'s floor sentence: the dependency and its level, against the resource's. */
+export declare function belowFloorMessage(entry: ReferenceTargetKind, ref: SpecReference, targetVisibility: ApiResourceVisibility, parentVisibility: ApiResourceVisibility): string;
+/** Clause (iii)'s one sentence — the same whether the target is missing or not platform-visible. */
+export declare function notAvailableReferenceMessage(entry: ReferenceTargetKind, ref: SpecReference): string;
+/**
+ * The refusal for a set of verdicts, or undefined when every one is ok.
+ * Missing same-organization targets are grouped per kind into one sentence
+ * (the contract's shape); every other refusal is its own sentence; the
+ * sentences are joined in the order the references were read. A no-org
+ * reference is malformed input (INVALID_ARGUMENT); everything else is a
+ * precondition the store does not meet (FAILED_PRECONDITION), the code the
+ * MCP-server contract already answers.
+ */
+export declare function referenceRefusal(parent: ReferenceParent, verdicts: ReadonlyArray<{
+    readonly ref: SpecReference;
+    readonly verdict: ReferenceVerdict;
+}>): ReturnType<typeof failedPreconditionError> | undefined;
+export declare function newNormalizeReferencesStep<Desc extends DescMessage>(): PipelineStep<Desc>;
+export declare function newValidateReferencesStep<Desc extends DescMessage>(store: Store): PipelineStep<Desc>;
+/** The rule over a collected list: load once, check each, render the refusal. */
+export declare function checkReferences(store: Store, parent: ReferenceParent, refs: ReadonlyArray<SpecReference>): Promise<ReturnType<typeof referenceRefusal>>;
+/** The references a stored row carries, for the escalation door; a chain passes one collector per place its row keeps them. */
+export type ReferenceCollector = (row: Message) => ReadonlyArray<SpecReference>;
+/**
+ * The floor's second door (the module header): on an updateVisibility chain,
+ * after the loaded row is on the context under `targetKey` and after
+ * ValidateVisibilityUpdate, refuses raising the level while a run-read
+ * reference the row carries would end below it.
+ */
+export declare function newGuardReferenceFloorOnEscalationStep(store: Store, targetKey: string, collectors: ReadonlyArray<ReferenceCollector>): PipelineStep<typeof UpdateVisibilityInputSchema>;
 /**
- * Every ApiResourceReference in a resource's spec — the same walk
- * ValidateReferences runs, exported for the readers that ask the reverse
- * question ("who references this?"): the plugin delete guard scans an
- * organization's agents and workflows for references to a member it is
- * about to remove.
+ * Every ApiResourceReference in a resource's spec, each with the kind its
+ * field declares — the walk both steps run, exported for the readers that
+ * ask the reverse question ("who references this?"): the plugin delete
+ * guard scans an organization's agents and workflows for references to a
+ * member it is about to remove.
  */
 export declare function collectSpecReferences(schema: DescMessage, msg: Parameters<typeof reflect>[1]): SpecReference[];
 //# sourceMappingURL=references.d.ts.map

package/dist/pipeline/steps/references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAIrD,OAAO,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AAEtH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAQnD,wBAAgB,0BAA0B,CACxC,IAAI,SAAS,WAAW,KACrB,YAAY,CAAC,IAAI,CAAC,CAwBtB;AAED,wBAAgB,yBAAyB,CAAC,IAAI,SAAS,WAAW,EAChE,KAAK,EAAE,KAAK,GACX,YAAY,CAAC,IAAI,CAAC,CA0CpB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GACjC,aAAa,EAAE,CAUjB"}
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/references.ts"],"names":[],"mappings":"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"}