@vibe-agent-toolkit/agent-skills 0.2.0-rc.2 → 0.2.0-rc.4

package/dist/projection/skill-extent.d.ts

@@ -0,0 +1,247 @@
+/**
+ * The **skill** extent, expressed as the generic closure primitive plus a
+ * declaration — zones.md §7.3's adequacy test, run for real.
+ *
+ * §7.3 requires that *a built-in extent must be expressible the way a
+ * config-declared one would be*. A skill bundle is the hardest case VAT has,
+ * because a privileged walker (`walk-link-graph.ts`) already computes it, so
+ * this module is the falsification: it translates a `SkillPackagingConfig` into
+ * an {@link ExtentDeclaration} and hands it to `ClosureExtentContributor`. There
+ * is deliberately **no bespoke walker here**. A second walker that passed its
+ * own tests would prove nothing about the primitive — it would only prove that
+ * the skill contributor can stay privileged, which is the outcome §17 risk 3
+ * asks about.
+ *
+ * ## What the primitive expresses, measured against the shipped walker
+ *
+ * The equality experiment lives in `test/projection-skill-extent.test.ts`, and
+ * its result is that **membership** agrees exactly on a corpus whose every link
+ * target is an ordinary reachable file, and — since the primitive gained a
+ * labelled `refusals` cascade plus `admitPaths` — on three of the cascade
+ * discriminators that used to diverge, and now on their REASONS as well. What
+ * remains is listed below. Stated here rather than in a report, because a reader
+ * reaching for this translation needs the boundary, not the anecdote:
+ *
+ * | Walker feature | Verdict |
+ * |---|---|
+ * | `linkFollowDepth` *membership* | **expressible** — same union, same off-by-one (`depth < maxDepth`) |
+ * | `depth-exceeded` *the REASON* | **expressible** — and it moved out of the not-expressible list once the primitive stopped guarding ENUMERATION on `maxDepth` and started guarding only ADMISSION. A member at the bound now has its references resolved and judged, and one the budget alone turns away becomes a `CLOSURE_DEPTH_EXCEEDED` condition carrying the same provenance a refusal does. This is the one verdict a DECLARATION states directly rather than through a `refusals` rule, so it carries no label and `matchedPattern` is null — which is exactly what the walker's own row says (`makeExclusion` attaches `matchedRule` only for `pattern-matched`) |
+ * | `excludeReferencesFromBundle` *membership* | **expressible** — first-match-wins and any-match select the same file set; carried as ONE refusal rule per declared rule, in declared order, which selects the same set the flat union did |
+ * | `excludeReferencesFromBundle` *WHICH rule matched* | **expressible** — one refusal rule apiece means the primitive's first-match-wins scan is `excludeMatchers.find(...)`'s scan, and the winner's first pattern lands in `realization_conditions.matchedPattern`, the column `packaging-validator.ts` reads as `matchedRule.patterns[0]` |
+ * | `excludeReferencesFromBundle` *`template` payload* | **expressible** — carried verbatim in `ExtentRefusalRule.payload` (opaque to the primitive) and reported as `realization_conditions.matchedPayload`, beside the rule's declared index. ⚠️ Never MEASURED against the walker: no shipped config declares a `template`, so the corpus shadow synthesizes one to compare the two arms |
+ * | `excludeNavigationFiles` | **expressible** — a refusal rule over `NAVIGATION_FILE_PATTERNS`, gated on the knob exactly as `classifyExclusion` gates its branch |
+ * | `agent-instruction-file` *membership* | **expressible** — a refusal rule over `AGENT_INSTRUCTION_FILE_PATTERNS`, unconditionally, and the explicit-`files:` escape hatch becomes `admitPaths` (see {@link declaredAgentInstructionSources}) |
+ * | `directory-target` *membership* | **expressible** — a refusal rule over `kinds: ['directory']`, which reads `resources.kind`; a path glob cannot express it, because a directory's path is shaped like a file's |
+ * | the REASON of those four exclusions | **expressible** — each refusal rule carries a `label`, and the first-match-wins order is `classifyExclusion`'s own branch order, so the refusal reports `SKILL_REFUSED_DIRECTORY_TARGET` where the walker reports `directory-target`. Pinned by the corpus shadow's reason-mismatch bucket, not asserted here |
+ * | `deferredArtifacts` (`files:`) | **not expressible** — its three-way classification is keyed on filesystem existence and on gitignore, and the closure does no I/O by construction. Only the ONE fact `admitPaths` needs — which sources are explicit, non-glob agent-instruction files — is a pure function of the config, which is why that much survives the translation |
+ * | `gitignored` | **expressible, CONDITIONALLY** — a COLUMN match, not an oracle: `resource_realizations.gitignored` is a first-class boolean the registry crawl fills, and `ExtentRefusalRule.flags` reads boolean columns. Carried as `{ gitignored: true, exists: true }` — a CONJUNCTION, because `classifyGitignored` is existence-gated — and emitted only when the population has a `GitTracker`, since without one the column is `false` on every row. ⚠️ Two bounds: the WALKER needs no tracker (it spawns `git check-ignore`), so the arms diverge in the no-tracker state; and `classifyGitignoredTarget` turns a gitignored `files:` DEST into a `deferred` verdict rather than a refusal, which no declaration can say (`admitPaths` would make it a member) |
+ * | `skill-definition` | **expressible**, as two halves that were always two verdicts under one `if`. The cross-skill half is an ordinary `basenames: ['SKILL.md']` rule, sitting between the agent-instruction rule and the globs exactly where `classifyExclusion` puts it. The self-link half is the walker's `{ kind: 'skipped' }`, and it is not a rule: the PRIMITIVE now skips a reference resolving to `closureFrom`, because the root is a member by declaration in any closure — see `closure-extent.ts`'s `hopFor`. ⚠️ The walker compares the basename with `===`; `basenames` folds case, so `Skill.md` diverges — see {@link SKILL_DEFINITION_BASENAME} |
+ * | `outside-project` | **expressible as a REASON, not as a full row** — and it never needed an oracle: `relativize` states every path against the root, and one the root does not contain comes back `..`-prefixed. It was a LABELLING gap, not a knowledge gap; the closure knew, and reported `CLOSURE_REFERENCE_UNRESOLVED`, which is true and useless. It is now `CLOSURE_REFERENCE_OUTSIDE_ROOT`, naming the same target the walker's row names. ⚠️ `targetExists` stays null: the walker `stat`s the escaping path, a projection populated from one root observes nothing outside it |
+ * | `missing-target` | **not expressible** — and NOT for the reason the column suggests. `exists` is a real column and `flags` reads it, but no rule can ever fire on it here: a path that is not on disk is never ENUMERATED, so it has no realization for a candidate to be, and the reference resolves to nothing long before the cascade runs. The producer is structurally blind, so the matcher is dead. The fact is still reported — as `CLOSURE_REFERENCE_UNRESOLVED` — but that code conflates "absent" with "present and not enumerated by any contributor", and only a filesystem probe separates them |
+ * | routable vs non-routable | **not expressible** (reasoned, not measured — the corpus has no HTML), and the earlier reason given here was wrong. The declaration is not short of a COLUMN: `resource_realizations.ext` carries the extension and `blobs.contentKey` is literally `<parserKind>.<sha256>`. What it is short of is a VERDICT: `isRoutable` makes an HTML page a member that is not traversed THROUGH, and the primitive has no admit-but-do-not-traverse outcome — a refusal would drop a file the walker bundles. Expressing it means a new verdict in the primitive, not a new matcher |
+ * | `unreadable-target` | **not expressible** — the one genuine oracle left. It is `existsSync` true AND `statSync` throwing anyway, a read outcome no column records: `contentState: 'unreadable'` is a *different* fact (a BYTE read that threw) and is demand-driven besides, so a path nobody asked to hash reads `deferred` whether or not it is stattable |
+ * | a refusal's PROVENANCE (`sourcePath`, `sourceLine`, `linkHref`, `targetExists`, `matchedRule`) | **expressible** — `realization_conditions` gained the six columns (projection schema v4), the closure fills them at the refusal site, and every one of the five is compared field by field against the walker's own row by the corpus shadow's provenance bucket |
+ *
+ * Read the membership, reason and provenance rows together: the primitive now
+ * selects the same files for those causes, names the same cause, and carries the
+ * same `sourcePath`/`sourceLine`/`linkHref`/`targetExists`/matched-rule
+ * provenance the walker attaches to a refusal.
+ *
+ * ## The residue is TWO reasons, not six — and one of them is not an oracle problem
+ *
+ * The count above used to be six, and four of those six were stale. Three had
+ * gained the machinery to express them (`gitignored` became a boolean column of
+ * the realization row; `outside-project` was always path math the closure was
+ * already doing; `skill-definition` needed one basename rule plus a self-link
+ * rule the primitive owes every closure), and one — `missing-target` — was
+ * inexpressible for a completely different reason than "no oracle": its matcher
+ * exists and can never fire, because the producer never emits the row it would
+ * match.
+ *
+ * What is left is `unreadable-target`, a genuine filesystem read outcome, and
+ * routability, which needs a new VERDICT in the primitive rather than a new
+ * matcher. Both are stated above with the evidence for the claim, because a
+ * boundary list that is never re-derived is how four verdicts stayed wrong for
+ * three increments.
+ *
+ * ⚠️ **Neither new verdict is measured against the walker on the real corpus,
+ * and they are not equally unmeasured elsewhere. Stated per verdict, because an
+ * aggregate "verified" would be false for one of them.**
+ *
+ * - **`skill-definition` IS measured against the walker, at FIXTURE scale.**
+ *   `projection-skill-extent.test.ts` builds a corpus containing a sibling
+ *   `skills/tool-b/SKILL.md`, and that divergence — named there, as a
+ *   one-element equality — closes when this rule lands.
+ * - **`gitignored` is reasoned, not measured against the walker anywhere.** The
+ *   `flags` conjunction it is made of has its own falsifying case in
+ *   `projection-closure-extent.test.ts` (including the `exists: false` control
+ *   that separates AND from OR), but no fixture yet links a skill to a gitignored
+ *   file with both arms running, so no two-arm comparison has ever exercised it.
+ *
+ * Neither is reachable on the REAL corpus, and that is asserted rather than
+ * assumed: the corpus shadow was green with both verdicts unexpressed, which is
+ * possible only if no declared skill links to a gitignored file or to another
+ * skill's SKILL.md, and both populations are now pinned at zero there. The day a
+ * link appears the test fails and the reader learns the corpus grew teeth
+ * ([[fixtures-that-cannot-distinguish]]).
+ *
+ * The `excludeNavigationFiles` row is the one worth reading twice, because the
+ * shape of its extension is the argument for why a rule needs a basename matcher
+ * and not a cleverer glob: `isNavigationBasename` matches a **case-insensitive
+ * basename set** (`README.md`, `index.md`, …), while `patterns` is picomatch
+ * over a root-relative path. A brace alternation over `README` / `readme` /
+ * `Readme` enumerates spellings a case-insensitive filesystem generates freely,
+ * so the approximation silently under-matches exactly where the walker's comment
+ * says it must not (`Claude.md` is loaded as instructions on APFS just as
+ * `CLAUDE.md` is). The honest extension was a declared basename set, and it is
+ * what `ExtentRefusalRule.basenames` is.
+ *
+ * ## `closureFrom` is stated in projection coordinates
+ *
+ * {@link skillExtentDeclaration} takes the SKILL.md path **relative to the
+ * corpus root**, the way `resource_realizations.path` spells it, because that is
+ * the only coordinate system `closureFrom` is resolved in. The packager works in
+ * absolute paths; converting is the caller's job precisely because the caller is
+ * the one holding the root.
+ */
+import { type ContributorStratum, type ExtentContribution, type ExtentContributor, type ExtentDeclaration, type JsonValue, type ProjectionBase, type SkillPackagingConfig } from '@vibe-agent-toolkit/resources';
+/**
+ * `zone_provenance.contributorId` prefix for a skill extent.
+ *
+ * **Per-skill, not fixed.** The plan specced a bare `builtin:skill`, which was
+ * written before anyone asked how many skills a corpus has:
+ * `ContributorRegistry.register` refuses a duplicate id, so a fixed id caps a
+ * population at **one** skill extent — and this repo alone ships thirteen. The
+ * extent ids were already distinct (the skill name is the within-root
+ * discriminator); only the contributor key space collided. Nothing schema-level
+ * objects: `zone_provenance.contributorId` is an open string.
+ */
+export declare const SKILL_EXTENT_CONTRIBUTOR_ID_PREFIX = "builtin:skill";
+/**
+ * The `zone_provenance.contributorId` for one skill's extent.
+ *
+ * @param skillName - The skill's name
+ * @returns The contributor id, unique per skill
+ */
+export declare function skillExtentContributorId(skillName: string): string;
+/** The `resolution_contexts.kind` a skill extent has. */
+export declare const SKILL_EXTENT_KIND = "skill";
+/**
+ * The refusal labels this translation supplies — **one per branch of the walker's
+ * exclusion cascade that a declaration can express**, and that property rather
+ * than a count is the definition: every `SKILL_REFUSED_*` constant below is a
+ * member, so adding a branch adds a member without falsifying this line. (The
+ * branches come from three classifiers, not one: `classifyExclusion`,
+ * `classifyPathKind` and `classifyGitignored` — each label's own doc line names
+ * which.)
+ *
+ * SCREAMING_SNAKE because they land in `realization_conditions.code`, whose two
+ * existing members (`CLOSURE_REFERENCE_UNRESOLVED`, `CLOSURE_ROOT_ABSENT`) set
+ * that convention. Prefixed `SKILL_REFUSED_` because that column is an OPEN
+ * vocabulary shared by every contributor in a population: a bare
+ * `DIRECTORY_TARGET` would not say whose cascade decided it.
+ *
+ * The walker reason each one stands for is in its own doc line, and that mapping
+ * is asserted end-to-end by the corpus shadow's reason-mismatch bucket rather
+ * than trusted — see `projection-skill-extent-corpus.integration.test.ts`.
+ */
+/** `classifyPathKind`'s `directory-target`. */
+export declare const SKILL_REFUSED_DIRECTORY_TARGET = "SKILL_REFUSED_DIRECTORY_TARGET";
+/** `classifyExclusion`'s `navigation-file`. */
+export declare const SKILL_REFUSED_NAVIGATION_FILE = "SKILL_REFUSED_NAVIGATION_FILE";
+/** `classifyExclusion`'s `agent-instruction-file`. */
+export declare const SKILL_REFUSED_AGENT_INSTRUCTION_FILE = "SKILL_REFUSED_AGENT_INSTRUCTION_FILE";
+/** `classifyExclusion`'s `pattern-matched`, from `excludeReferencesFromBundle`. */
+export declare const SKILL_REFUSED_PATTERN_MATCHED = "SKILL_REFUSED_PATTERN_MATCHED";
+/**
+ * `classifyExclusion`'s `skill-definition` — ANOTHER skill's SKILL.md.
+ *
+ * Only the cross-skill half. The walker's branch is two verdicts wearing one
+ * `if`: a link to a *sibling's* SKILL.md is this refusal, and a link back to the
+ * walk's OWN `skillRootPath` is `{ kind: 'skipped' }` — recorded nowhere. The
+ * declaration expresses the first as an ordinary basename rule; the second is
+ * not a rule at all, and it is the primitive that supplies it, because a
+ * reference to `closureFrom` is a self-link in any closure and not a fact about
+ * skills (see `closure-extent.ts`'s `hopFor`).
+ */
+export declare const SKILL_REFUSED_SKILL_DEFINITION = "SKILL_REFUSED_SKILL_DEFINITION";
+/** `classifyGitignored`'s `gitignored`, existence-gated exactly as that branch is. */
+export declare const SKILL_REFUSED_GITIGNORED = "SKILL_REFUSED_GITIGNORED";
+/**
+ * Translate a skill's packaging config into a closure-extent declaration.
+ *
+ * This is the whole of the skill extent's behaviour: everything else is the
+ * generic contributor. `linkFollowDepth` becomes `maxDepth` unchanged (same
+ * `number | 'full'` union, same meaning of a hop), and {@link skillRefusals}
+ * becomes the cascade — one rule per `classifyExclusion` branch this translation
+ * can express, in that function's own order.
+ *
+ * ⚠️ This paragraph used to say the `excludeReferencesFromBundle` rules
+ * "flatten into ONE labelled refusal rule". They have not since the increment
+ * that restored `matchedRule`: they expand to one rule EACH, in declared order,
+ * which is what lets `realization_conditions.matchedPattern` name WHICH rule
+ * caught a file. The `template` it also said the primitive had "nowhere to put"
+ * rides in that rule's opaque `payload`.
+ *
+ * `follow` is left to the schema default (the three markdown forms), matching
+ * the walker: it processes only `isLocalFileLink` links off the markdown AST, so
+ * an `@`-prefixed or bare token is not an edge on either side.
+ *
+ * @param config - The skill's `skills.config.<name>` packaging block
+ * @param skillPath - The SKILL.md path **relative to the corpus root**, forward-slashed
+ * @param hasGitTracker - Whether the population this declaration will run in was
+ *   given a usable git oracle. Not "should gitignored files be refused": the
+ *   column that rule reads is unfilled without one, so declaring it anyway would
+ *   claim a branch that cannot run. REQUIRED rather than defaulted, because a
+ *   defaulted `false` would let a caller that does have a tracker silently ship a
+ *   declaration missing the last rule of the cascade — a no-op wearing a fix
+ * @returns The declaration, schema-parsed so every default is materialized
+ * @throws When the resulting declaration is not schema-valid — e.g. an empty `skillPath`
+ */
+export declare function skillExtentDeclaration(config: SkillPackagingConfig, skillPath: string, hasGitTracker: boolean): ExtentDeclaration;
+/**
+ * The skill extent — `ClosureExtentContributor` under a fixed id and kind.
+ *
+ * Delegation rather than inheritance, and the thinness is the finding: if this
+ * class needed to *do* anything, the closure primitive would have been
+ * inadequate and the skill contributor would have stayed privileged. It owns
+ * only the two things the registry reads before `contribute` runs — a stable
+ * `id` for `zone_provenance`, and the `kind` `ContributorRegistry.forKind`
+ * partitions on.
+ *
+ * **One instance per skill**, keyed by {@link skillExtentContributorId}. A fixed
+ * id would cap a population at one skill extent, because
+ * `ContributorRegistry.register` refuses a duplicate — see that function.
+ */
+export declare class SkillExtentContributor implements ExtentContributor {
+    #private;
+    readonly id: string;
+    readonly kind: string;
+    readonly stratum: ContributorStratum;
+    /**
+     * Delegated, never restated: this contributor's `contribute` is the
+     * delegate's, so whether it reads blob-keyed tables is the delegate's answer
+     * and a hard-coded `true` here would be a second copy free to drift.
+     */
+    get readsBlobs(): boolean;
+    /**
+     * @param skillName - The skill's name. Discriminates both the contributor id
+     *   and, through the delegate, the extent's within-root context id — one
+     *   source for both, so the two cannot drift apart.
+     */
+    constructor(skillName: string);
+    /**
+     * Produce the skill extent by running the closure primitive.
+     *
+     * Not `async`: the delegate's promise is returned directly, so there is no
+     * second microtask and no place for this method to add behaviour.
+     *
+     * @param base - Everything merged so far — the realizations a reference can
+     *   resolve to, and the `blob_references` rows that are the edges
+     * @param parameters - A {@link skillExtentDeclaration} result, arriving as
+     *   config data exactly as a user-declared extent would
+     * @returns The extent's context, members, realizations and conditions
+     */
+    contribute(base: ProjectionBase, parameters: JsonValue): Promise<ExtentContribution>;
+}
+//# sourceMappingURL=skill-extent.d.ts.map

package/dist/projection/skill-extent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-extent.d.ts","sourceRoot":"","sources":["../../src/projection/skill-extent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAIH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEtB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AASvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,kBAAkB,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAyCzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CAA+C;AAC/C,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAE/E,+CAA+C;AAC/C,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E,sDAAsD;AACtD,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F,mFAAmF;AACnF,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAE/E,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AA+QnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,GACrB,iBAAiB,CAQnB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAqB;IAE1C,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAa;IAKjD;;;;OAIG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;OAIG;gBACS,SAAS,EAAE,MAAM;IAK7B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGrF"}