@ploaness/governance 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herman Ciechanowiec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @ploaness/governance
+
+Pure, unit-tested governance rules for ploaness. No filesystem, process, or network access.
+
+This package is published as part of `ploaness` and is not meant to be depended on directly. Install `ploaness`, which re-exports what a project needs.
+
+## Documentation
+
+<https://github.com/ciechanowiec/ploaness#readme>
+
+## License
+
+MIT. See the LICENSE file in this package.

package/dist/access-boundary.d.ts

@@ -0,0 +1,41 @@
+import type { PublicAccess } from './settings.js';
+/**
+ * One operation's verdict as Payload sends it: `true` for an unconstrained grant, `{ permission: true,
+ * where }` for a constrained one, and absent for a denial, which Payload deletes from the response.
+ */
+export type ReportedPermission = boolean | {
+    readonly permission?: boolean;
+    readonly where?: unknown;
+};
+/** One entity's operations, keyed as Payload keys them. */
+export type ReportedEntity = Readonly<Record<string, ReportedPermission>>;
+/** The body of `/api/access`, read for the operations alone. */
+export interface AccessReport {
+    readonly canAccessAdmin?: boolean;
+    readonly collections?: Readonly<Record<string, ReportedEntity>>;
+    readonly globals?: Readonly<Record<string, ReportedEntity>>;
+}
+/** One permission the running application actually grants. */
+export interface Granted {
+    readonly entity: string;
+    readonly operation: string;
+}
+/**
+ * A write is never a default a project should be able to reach by accident: Payload grants none of these
+ * to an anonymous caller unless the project's own rule says so. `read` is judged too, but it is the one
+ * a public site legitimately grants, which is what `publicAccess` exists to record.
+ */
+export declare const JUDGED_OPERATIONS: readonly string[];
+/** Whether Payload reported this operation as permitted, in either of the two shapes it sends. */
+export declare const isPermitted: (permission: ReportedPermission | undefined) => boolean;
+/** Every permission an access report grants, across collections and globals alike. */
+export declare const grantedPermissions: (report: AccessReport) => readonly Granted[];
+/** How one grant is named, both in a report and in the `publicAccess` entry that would declare it. */
+export declare const describeGrant: (granted: Granted) => string;
+/**
+ * The grants the running application makes to a stranger that the project has not recorded. Empty is
+ * the only passing answer: a project that declares nothing is judged most strictly, and a declaration
+ * narrows nothing else.
+ */
+export declare const undeclaredGrants: (report: AccessReport, declared: readonly PublicAccess[]) => readonly string[];
+//# sourceMappingURL=access-boundary.d.ts.map

package/dist/access-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-boundary.d.ts","sourceRoot":"","sources":["../src/access-boundary.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAA;AAEzE,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;CAC5D;AAED,8DAA8D;AAC9D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAA2C,CAAA;AAE1F,kGAAkG;AAClG,eAAO,MAAM,WAAW,GAAI,YAAY,kBAAkB,GAAG,SAAS,KAAG,OACO,CAAA;AAUhF,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,SAAS,OAAO,EAGzE,CAAA;AAED,sGAAsG;AACtG,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,KAAG,MAAkD,CAAA;AAQnG;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,YAAY,EACpB,UAAU,SAAS,YAAY,EAAE,KAChC,SAAS,MAAM,EAG4C,CAAA"}

package/dist/access-boundary.js

@@ -0,0 +1,26 @@
+/**
+ * A write is never a default a project should be able to reach by accident: Payload grants none of these
+ * to an anonymous caller unless the project's own rule says so. `read` is judged too, but it is the one
+ * a public site legitimately grants, which is what `publicAccess` exists to record.
+ */
+export const JUDGED_OPERATIONS = ['create', 'read', 'update', 'delete'];
+/** Whether Payload reported this operation as permitted, in either of the two shapes it sends. */
+export const isPermitted = (permission) => typeof permission === 'boolean' ? permission : permission?.permission === true;
+const grantsIn = (entities) => Object.entries(entities).flatMap(([entity, permissions]) => JUDGED_OPERATIONS.filter((operation) => isPermitted(permissions[operation])).map((operation) => ({ entity, operation })));
+/** Every permission an access report grants, across collections and globals alike. */
+export const grantedPermissions = (report) => [
+    ...grantsIn(report.collections ?? {}),
+    ...grantsIn(report.globals ?? {}),
+];
+/** How one grant is named, both in a report and in the `publicAccess` entry that would declare it. */
+export const describeGrant = (granted) => `${granted.entity}.${granted.operation}`;
+const isDeclared = (granted, declared) => declared.some((entry) => entry.entity === granted.entity && entry.operation === granted.operation);
+/**
+ * The grants the running application makes to a stranger that the project has not recorded. Empty is
+ * the only passing answer: a project that declares nothing is judged most strictly, and a declaration
+ * narrows nothing else.
+ */
+export const undeclaredGrants = (report, declared) => grantedPermissions(report)
+    .filter((granted) => !isDeclared(granted, declared))
+    .map((granted) => describeGrant(granted));
+//# sourceMappingURL=access-boundary.js.map

package/dist/access-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-boundary.js","sourceRoot":"","sources":["../src/access-boundary.ts"],"names":[],"mappings":"AAyCA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAE1F,kGAAkG;AAClG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAA0C,EAAW,EAAE,CACjF,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAA;AAEhF,MAAM,QAAQ,GAAG,CAAC,QAAkD,EAAsB,EAAE,CAC1F,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAC9B,CAAC,CAAC,MAAM,EAAE,WAAW,CAAoC,EAAsB,EAAE,CAC/E,iBAAiB,CAAC,MAAM,CAAC,CAAC,SAAiB,EAAW,EAAE,CACtD,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CACpC,CAAC,GAAG,CAAC,CAAC,SAAiB,EAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CACjE,CAAA;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAoB,EAAsB,EAAE,CAAC;IAC9E,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;IACrC,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;CAClC,CAAA;AAED,sGAAsG;AACtG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAgB,EAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAA;AAEnG,MAAM,UAAU,GAAG,CAAC,OAAgB,EAAE,QAAiC,EAAW,EAAE,CAClF,QAAQ,CAAC,IAAI,CACX,CAAC,KAAmB,EAAW,EAAE,CAC/B,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS,CAC3E,CAAA;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,MAAoB,EACpB,QAAiC,EACd,EAAE,CACrB,kBAAkB,CAAC,MAAM,CAAC;KACvB,MAAM,CAAC,CAAC,OAAgB,EAAW,EAAE,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;KACrE,GAAG,CAAC,CAAC,OAAgB,EAAU,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAA"}

package/dist/agent-references.d.ts

@@ -0,0 +1,12 @@
+export interface AgentReferenceMatch {
+    readonly line: number;
+    readonly label: string;
+}
+/**
+ * Scans text for references that attribute a change to an AI agent or its session, reporting the
+ * 1-based line and the kind of attribution matched.
+ * @param text the content to scan, with lines separated by "\n".
+ * @returns one match per attribution marker found, in reading order.
+ */
+export declare const findAgentReferences: (text: string) => readonly AgentReferenceMatch[];
+//# sourceMappingURL=agent-references.d.ts.map

package/dist/agent-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-references.d.ts","sourceRoot":"","sources":["../src/agent-references.ts"],"names":[],"mappings":"AAqDA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAQD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,SAAS,mBAAmB,EAK1E,CAAA"}

package/dist/agent-references.js

@@ -0,0 +1,53 @@
+// Shared AI-agent attribution ban: a governed repository's history must not record which automated
+// agent, or which agent session, produced a change. Commit messages therefore carry no co-authorship
+// trailer, vendor sign-off email, session identifier, or generated-by signature that attributes the
+// change to an AI agent. This module is the single source of truth for the known attribution patterns;
+// the `commit-history` gate in packages/cli/src/checks/history.ts consumes it. Only structured attribution markers
+// are matched, never a bare product name in prose: this repository ships agent instructions and
+// documents such tools by name, so a commit like "docs: explain the claude code skill" must pass.
+// Named automated coding agents and their vendors, as one alternation fragment reused across patterns.
+// The set is the "known ones" the ban targets; extend it as new agents appear (no pattern can know them
+// all, so the guideline also states the rule in prose for an inspector to apply).
+const AGENT_NAMES = [
+    'claude|anthropic|copilot|cursor|codex|chatgpt|openai',
+    'gpt(?:[- ][0-9a-z.]+)?|devin|aider|windsurf|opencode',
+    'gemini|bard|codeium|tabnine|sourcegraph|cody',
+].join('|');
+const AGENT_REFERENCE_PATTERNS = [
+    {
+        // A co-authorship trailer naming a known agent, e.g. "Co-Authored-By: Claude <...>".
+        pattern: new RegExp(String.raw `co-authored-by:[^\n]*\b(?:${AGENT_NAMES})\b`, 'i'),
+        label: 'agent co-authorship trailer',
+    },
+    {
+        // An agent vendor's sign-off address, e.g. the "noreply@anthropic.com" author Claude Code stamps.
+        pattern: /\b[\w.+-]*@(?:anthropic|openai|cursor|devin|aider)\.(?:com|ai|dev)\b/i,
+        label: 'agent vendor email',
+    },
+    {
+        // A session identifier an agent stamps on its work, e.g. "Claude-Session:" or "Codex-Session-Id:".
+        pattern: new RegExp(String.raw `\b(?:${AGENT_NAMES}|agent|assistant)[- ]?session(?:[- ]?id)?\s*:`, 'i'),
+        label: 'agent session identifier',
+    },
+    {
+        // A generated-by signature, e.g. "Generated with Claude Code" or its robot-emoji-prefixed variant.
+        pattern: new RegExp(String.raw `generated\s+(?:with|by)\s.*\b(?:${AGENT_NAMES})\b`, 'i'),
+        label: 'agent generation signature',
+    },
+    {
+        // The Claude Code product signature link, e.g. "[Claude Code](https://claude.com/claude-code)".
+        pattern: /claude\.(?:ai|com)\/claude-code/i,
+        label: 'agent product signature',
+    },
+];
+const findMatchesInLine = (line, lineNumber) => AGENT_REFERENCE_PATTERNS.flatMap((entry) => entry.pattern.test(line) ? [{ line: lineNumber, label: entry.label }] : []);
+/**
+ * Scans text for references that attribute a change to an AI agent or its session, reporting the
+ * 1-based line and the kind of attribution matched.
+ * @param text the content to scan, with lines separated by "\n".
+ * @returns one match per attribution marker found, in reading order.
+ */
+export const findAgentReferences = (text) => text
+    .split('\n')
+    .flatMap((line, index) => findMatchesInLine(line, index + 1));
+//# sourceMappingURL=agent-references.js.map

package/dist/agent-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-references.js","sourceRoot":"","sources":["../src/agent-references.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,qGAAqG;AACrG,oGAAoG;AACpG,uGAAuG;AACvG,mHAAmH;AACnH,gGAAgG;AAChG,kGAAkG;AAOlG,uGAAuG;AACvG,wGAAwG;AACxG,kFAAkF;AAClF,MAAM,WAAW,GAAW;IAC1B,sDAAsD;IACtD,sDAAsD;IACtD,8CAA8C;CAC/C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAEX,MAAM,wBAAwB,GAAqC;IACjE;QACE,qFAAqF;QACrF,OAAO,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,6BAA6B,WAAW,KAAK,EAAE,GAAG,CAAC;QACjF,KAAK,EAAE,6BAA6B;KACrC;IACD;QACE,kGAAkG;QAClG,OAAO,EAAE,uEAAuE;QAChF,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,mGAAmG;QACnG,OAAO,EAAE,IAAI,MAAM,CACjB,MAAM,CAAC,GAAG,CAAA,QAAQ,WAAW,+CAA+C,EAC5E,GAAG,CACJ;QACD,KAAK,EAAE,0BAA0B;KAClC;IACD;QACE,mGAAmG;QACnG,OAAO,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,mCAAmC,WAAW,KAAK,EAAE,GAAG,CAAC;QACvF,KAAK,EAAE,4BAA4B;KACpC;IACD;QACE,gGAAgG;QAChG,OAAO,EAAE,kCAAkC;QAC3C,KAAK,EAAE,yBAAyB;KACjC;CACF,CAAA;AAOD,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAE,UAAkB,EAAkC,EAAE,CAC7F,wBAAwB,CAAC,OAAO,CAC9B,CAAC,KAA4B,EAAkC,EAAE,CAC/D,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAC7E,CAAA;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAY,EAAkC,EAAE,CAClF,IAAI;KACD,KAAK,CAAC,IAAI,CAAC;KACX,OAAO,CAAC,CAAC,IAAY,EAAE,KAAa,EAAkC,EAAE,CACvE,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CACnC,CAAA"}

package/dist/architecture-layers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The forbidden rule that keeps the declared pure-logic directories pure.
+ *
+ * Phrased as "these directories may depend on nothing else under a source root" rather than by listing
+ * the layers above them, so a new source directory is governed the moment it exists instead of when
+ * somebody remembers to add it here.
+ * @param pureLogicRoots the directories forming the floor, repo-relative and without a trailing slash.
+ * @returns the dependency-cruiser rule, or undefined when the project declares no floor.
+ */
+export declare const pureLogicRule: (pureLogicRoots: readonly string[]) => Record<string, unknown> | undefined;
+//# sourceMappingURL=architecture-layers.d.ts.map

package/dist/architecture-layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-layers.d.ts","sourceRoot":"","sources":["../src/architecture-layers.ts"],"names":[],"mappings":"AA2BA;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,gBAAgB,SAAS,MAAM,EAAE,KAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAmB5B,CAAA"}

package/dist/architecture-layers.js

@@ -0,0 +1,47 @@
+// The pure-logic floor, as data rather than as a fixed path.
+//
+// The architecture contract calls the layer map "the one genuinely project-shaped part" and then named
+// `src/access` and `src/lib` in a file a governed project is forbidden to own. A project that puts pure
+// logic somewhere else - a configuration layer, a domain directory - could satisfy the intent and still
+// fail the rule, with no way to say so. The floor is declared under the `ploaness` key now, and this
+// renders it into the shape the analyzer reads.
+/** The generated files the floor may depend on, which carry types rather than behaviour. */
+const TYPE_ONLY_ARTEFACTS = ['src/payload-types.ts'];
+// Every root is spliced into a regular expression, so it has to be escaped on the way in. It was not,
+// and both halves of that were live: `src/app/(payload)` - a real directory in a Payload project - read
+// as a capture group and matched `src/app/payload/` instead, and a glob-shaped root produced
+// `^(src/config/**\/)`, which is not a valid expression at all and took dependency-cruiser down with no
+// finding attached. The artefact list beside this one was already escaped; the roots were the half that
+// was missed.
+const REGEX_METACHARACTERS = /[$()*+.?[\\\]^{|}]/gu;
+// A trailing slash is normalised where the setting is read, so what arrives here is already a bare
+// directory. This escapes it, and nothing else.
+const asRoot = (directory) => directory.replaceAll(REGEX_METACHARACTERS, String.raw `\$&`);
+const alternation = (directories) => directories.map((directory) => `${asRoot(directory)}/`).join('|');
+/**
+ * The forbidden rule that keeps the declared pure-logic directories pure.
+ *
+ * Phrased as "these directories may depend on nothing else under a source root" rather than by listing
+ * the layers above them, so a new source directory is governed the moment it exists instead of when
+ * somebody remembers to add it here.
+ * @param pureLogicRoots the directories forming the floor, repo-relative and without a trailing slash.
+ * @returns the dependency-cruiser rule, or undefined when the project declares no floor.
+ */
+export const pureLogicRule = (pureLogicRoots) => {
+    if (pureLogicRoots.length === 0) {
+        return undefined;
+    }
+    const floor = alternation(pureLogicRoots);
+    const escaped = TYPE_ONLY_ARTEFACTS.map((artefact) => artefact.replaceAll('.', String.raw `\.`));
+    const exempt = escaped.map((artefact) => `^${artefact}$`).join('|');
+    return {
+        name: 'pure-logic-stays-pure',
+        severity: 'error',
+        comment: `${pureLogicRoots.join(' and ')} are the pure-logic floor: they must depend on nothing else ` +
+            'in src (only types and third-party libs). If you need framework data, pass it in as a plain ' +
+            'value. This is what keeps them unit-testable without mocks.',
+        from: { path: `^(${floor})` },
+        to: { path: '^src/', pathNot: `^(${floor})|${exempt}` },
+    };
+};
+//# sourceMappingURL=architecture-layers.js.map

package/dist/architecture-layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-layers.js","sourceRoot":"","sources":["../src/architecture-layers.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,uGAAuG;AACvG,wGAAwG;AACxG,wGAAwG;AACxG,qGAAqG;AACrG,gDAAgD;AAEhD,4FAA4F;AAC5F,MAAM,mBAAmB,GAAsB,CAAC,sBAAsB,CAAC,CAAA;AAEvE,sGAAsG;AACtG,wGAAwG;AACxG,6FAA6F;AAC7F,wGAAwG;AACxG,wGAAwG;AACxG,cAAc;AACd,MAAM,oBAAoB,GAAW,sBAAsB,CAAA;AAE3D,mGAAmG;AACnG,gDAAgD;AAChD,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAU,EAAE,CAC3C,SAAS,CAAC,UAAU,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAAG,CAAA,KAAK,CAAC,CAAA;AAE7D,MAAM,WAAW,GAAG,CAAC,WAA8B,EAAU,EAAE,CAC7D,WAAW,CAAC,GAAG,CAAC,CAAC,SAAiB,EAAU,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAEnF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,cAAiC,EACI,EAAE;IACvC,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAW,WAAW,CAAC,cAAc,CAAC,CAAA;IACjD,MAAM,OAAO,GAAsB,mBAAmB,CAAC,GAAG,CAAC,CAAC,QAAgB,EAAU,EAAE,CACtF,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAA,IAAI,CAAC,CACzC,CAAA;IACD,MAAM,MAAM,GAAW,OAAO,CAAC,GAAG,CAAC,CAAC,QAAgB,EAAU,EAAE,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC3F,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,QAAQ,EAAE,OAAO;QACjB,OAAO,EACL,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,8DAA8D;YAC7F,8FAA8F;YAC9F,6DAA6D;QAC/D,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,KAAK,GAAG,EAAE;QAC7B,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,KAAK,MAAM,EAAE,EAAE;KACxD,CAAA;AACH,CAAC,CAAA"}

package/dist/asset-policy.d.ts

@@ -0,0 +1,138 @@
+/** How ploaness treats a path in the consumer working tree. */
+export type Disposition = 'PINNED' | 'SEED' | 'FORBIDDEN' | 'SECTION' | 'REFERENCE';
+/**
+ * Where a managed path lives.
+ *
+ * REPOSITORY is what git, an editor or a coding agent reads from the tree root: one contract per
+ * repository, not one per package, and a second copy inside a member would be a second answer to the
+ * same question. APPLICATION is what belongs to a member that serves one - the executable sweeps, each
+ * interrogating one running server, so two applications are two sets of answers rather than one shared
+ * file. PAYLOAD narrows that to the members that can answer at all: the access-boundary sweep asks
+ * Payload itself what it grants an anonymous caller, and a Next application with no Payload has no such
+ * endpoint to ask. EVERYWHERE is for a forbidden path, where a copy at the root OR inside any member
+ * would shadow what ploaness supplies.
+ */
+export type AssetScope = 'REPOSITORY' | 'APPLICATION' | 'PAYLOAD' | 'EVERYWHERE';
+/** One catalogue entry: a repo-relative path, its disposition, and where it lives. */
+export interface ManagedAsset {
+    readonly path: string;
+    readonly disposition: Disposition;
+    readonly scope: AssetScope;
+}
+/** A managed-file defect found in the consumer working tree. */
+export interface AssetViolation {
+    readonly path: string;
+    readonly reason: string;
+}
+/** The working-tree facts the policy needs, injected so the core stays free of filesystem access. */
+export interface AssetState {
+    /** Whether the path is present in the consumer working tree. */
+    readonly isPresent: boolean;
+    /** The working-tree content, or undefined when the path is absent. */
+    readonly actual: string | undefined;
+    /** The content ploaness ships for the path, or undefined for a FORBIDDEN entry. */
+    readonly expected: string | undefined;
+}
+/** The outcome of parsing a manifest: the entries, and any rows too malformed to honour. */
+export interface ParsedManifest {
+    readonly assets: readonly ManagedAsset[];
+    readonly problems: readonly string[];
+}
+/** Opens the block ploaness owns inside a SECTION file. */
+export declare const SECTION_BEGIN: string;
+/** Closes the block ploaness owns inside a SECTION file. */
+export declare const SECTION_END: string;
+/**
+ * What a SECTION file currently carries. The three cases are not interchangeable: `absent` is a file
+ * ploaness may safely write into, `present` is a block it may compare and replace, and `malformed` is a
+ * file it must refuse, because every automatic repair of ambiguous markers risks swallowing or
+ * duplicating text the project owns.
+ */
+export type SectionState = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'present';
+    readonly block: string;
+} | {
+    readonly kind: 'malformed';
+    readonly reason: string;
+};
+/**
+ * Read back the ploaness-owned block, markers included.
+ *
+ * The markers are HTML comments so they survive in every Markdown renderer without being visible to a
+ * human reader, and so an agent editing the file below them can see exactly where its own territory
+ * starts. The block must lead the file and appear exactly once: a contract an agent reaches only after
+ * scrolling past the project's own prose is not the first thing it reads, and a second copy would let
+ * one block drift while the other stayed current.
+ * @param rawContent the whole file as it currently stands in the working tree.
+ * @returns which of the three states the file is in.
+ */
+export declare const readManagedSection: (rawContent: string) => SectionState;
+/**
+ * Put the ploaness-owned block into a file, preserving everything the project owns.
+ *
+ * An existing block is replaced where it stands, so the project text below it is carried through
+ * byte for byte. A file with no block gets one at the very top, because the contract has to be the
+ * first thing an agent reads.
+ * @param rawContent the current file, or the empty string when it does not exist yet.
+ * @param block the block ploaness ships, markers included.
+ * @returns the spliced file, or undefined when the markers are too ambiguous to edit safely.
+ */
+export declare const applyManagedSection: (rawContent: string, block: string) => string | undefined;
+/**
+ * Parse a manifest into catalogue entries. Blank lines and `#` comments are ignored; a row is a
+ * repo-relative path, a tab, and a disposition. A malformed row is reported rather than silently
+ * skipped, so a packaging mistake cannot quietly shrink the catalogue.
+ * @param manifest the raw manifest.tsv contents.
+ * @returns the parsed entries and any malformed rows.
+ */
+export declare const parseManifest: (manifest: string) => ParsedManifest;
+/**
+ * Judge one managed path against its disposition.
+ * @param asset the catalogue entry.
+ * @param state the working-tree facts for that path.
+ * @returns a violation, or undefined when the path conforms.
+ */
+export declare const checkAsset: (asset: ManagedAsset, state: AssetState) => AssetViolation | undefined;
+/**
+ * Judge every catalogue entry the project has not explicitly taken over.
+ * @param assets the parsed catalogue.
+ * @param unmanaged repo-relative paths the project owns instead.
+ * @param stateOf resolves the working-tree and shipped content for a path.
+ * @returns one violation per non-conforming path; empty means the tree matches the catalogue.
+ */
+export declare const findAssetViolations: (assets: readonly ManagedAsset[], unmanaged: readonly string[], stateOf: (path: string) => AssetState) => readonly AssetViolation[];
+/** What `ploaness sync` should do with one managed path. */
+export type SyncAction = 'write' | 'delete' | 'skip' | 'splice';
+/**
+ * Decide the sync action for one path. A PINNED file is always rewritten, so drift is repaired; a SEED
+ * file is written only when absent, so the project's own edits survive; a FORBIDDEN file is deleted; a
+ * SECTION file has only its marked block replaced.
+ * @param asset the catalogue entry.
+ * @param isPresent whether the path is currently present in the working tree.
+ * @returns the action `ploaness sync` performs.
+ */
+export declare const syncAction: (asset: ManagedAsset, isPresent: boolean) => SyncAction;
+/** What a member can hold a managed file for, derived from its kind. */
+export interface AssetHost {
+    readonly hasRuntime: boolean;
+    readonly isPayload: boolean;
+}
+/**
+ * The catalogue entries that apply at the repository root.
+ * @param assets the whole catalogue.
+ * @returns the repository-scope entries and the forbidden paths, which apply everywhere.
+ */
+export declare const repositoryAssets: (assets: readonly ManagedAsset[]) => readonly ManagedAsset[];
+/**
+ * The catalogue entries that apply inside one member.
+ *
+ * A library receives only the forbidden paths: it has no server to sweep, so a spec that drives one
+ * would be a managed file demanding a browser the package was never going to open.
+ * @param assets the whole catalogue.
+ * @param host what the member can hold, derived from its kind.
+ * @returns the entries that apply to that member.
+ */
+export declare const memberAssets: (assets: readonly ManagedAsset[], host: AssetHost) => readonly ManagedAsset[];
+//# sourceMappingURL=asset-policy.d.ts.map

package/dist/asset-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-policy.d.ts","sourceRoot":"","sources":["../src/asset-policy.ts"],"names":[],"mappings":"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"}