@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_load.py

@@ -0,0 +1,358 @@
+"""The call queue and the load report of DEC-0104 (contract `src/agent-network.ts`, FAC-SEM-131 to FAC-SEM-133), as the
+contract's reference answers them: a node that hosts a job-backed agent queues its jobs per (agentRef, context) with
+these and reports its load as `service-load/1` under `extensions/load/0.1`. Part of the service kit (FAA-289, layer L3);
+the twin of fabric-load.mjs. Standard library only. Nothing here raises on what it reads, except `load_extension`, which
+refuses a declaration a reader would treat as not declared.
+
+- job_caller_key(accepted, credential): the opaque key of a job's caller (an accepted delegation's principal, its
+  outermost actor and a partner organization ending the chain; else the credential the node knows the caller by).
+- next_queued_job(queue, running, limits): the job the node starts next, or None (fairness between callers).
+- admit_job(queue, running, job, limits, retry_after_seconds): {admit: True}, or the `queue-full` refusal with its data.
+- queue_status_message(position, length), read_queue_position(status_message): `queued <position> of <length>`.
+- job_queue_rules(value): FAC-SEM-131 over {queue, running, limits, started}.
+- load_report_rules(report): FAC-SEM-132 on a `service-load/1` report; load_report_problems(report): its schema.
+- load_view(well_known), load_extension_rules(well_known): the declaration as a reader reads it, and FAC-SEM-133.
+- load_extension(path, window_seconds, limits): the `extensions` entry a service declares.
+
+The kit has no JSON Schema validator: the two shapes are written here from the schemas as the contract's validator
+reads them (ECMAScript's \\s in patterns, lengths in code points, `date-time` as ajv-formats' full mode). Times in the
+queue are UTC instants (`interop-common#/$defs/utcInstant`); times in the report are RFC 3339 read strictly (the
+contract's strictTime). The wording of a schema problem is the kit's, not ajv's."""
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Dict, List, Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+
+from fabric_base import ServiceError  # noqa: E402
+from fabric_connections import date_time  # noqa: E402 - ajv-formats' date-time, as the contract's validator reads it
+from fabric_jsvalue import (  # noqa: E402
+    MISSING, _JS_SPACE, double, get, is_number, json_stringify, objects, safe_integer, same, show,
+)
+from fabric_time import parse_rfc3339_ms  # noqa: E402 - the contract's strictTime
+
+LOAD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/load/0.1"
+LOAD_REPORT_TYPE = "service-load/1"
+#: The refusal code, the same as fabric_interop_rules.QUEUE_FULL (a test holds them equal); not imported because the
+#: facade fabric_service, which re-exports this module, comes before the interop rules in the kit's order.
+_QUEUE_FULL = "queue-full"
+QUEUE_FULL_MESSAGE = "the agent's queue for this context is full: start again later"
+#: The longest queue a status message names (`queued <position> of <length>`, six digits).
+QUEUE_LENGTH_MAX = 999999
+DEFAULT_RETRY_AFTER_SECONDS = 60
+
+_UTC_INSTANT = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9](?:\.[0-9]{1,3})?Z", re.ASCII)
+_QUEUED = re.compile(r"queued ([1-9][0-9]{0,5}) of ([1-9][0-9]{0,5})", re.ASCII)
+_ORIGIN_PATH = re.compile("/(?!/)[^%s]*" % re.escape(_JS_SPACE))
+_CONTEXT = re.compile(r"(?:personal|org:[A-Za-z0-9][A-Za-z0-9_-]{0,127})", re.ASCII)
+_KEY_PATH = "/extensions/" + LOAD_EXTENSION_KEY.replace("~", "~0").replace("/", "~1")
+_LIMITS = (("concurrency", 1, 1024), ("perCaller", 1, 1024), ("queueMax", 0, 100000))
+_ROW_COUNTS = ("queued", "running", "completed", "failed")
+
+
+def _utc_ms(value: Any) -> float:
+    """A UTC instant (`T`, `Z`, at most three fraction digits, a day that exists) in milliseconds, else NaN."""
+    return parse_rfc3339_ms(value) if isinstance(value, str) and _UTC_INSTANT.fullmatch(value) else math.nan
+
+
+def _strict_ms(value: Any) -> float:
+    return parse_rfc3339_ms(value) if isinstance(value, str) else math.nan
+
+
+def _utf16(value: str) -> bytes:
+    """A key that orders strings as JavaScript's `<` does: by UTF-16 code units."""
+    return value.encode("utf-16-be", "surrogatepass")
+
+
+def _string(value: Any) -> bool:
+    return isinstance(value, str)
+
+
+# --- The call queue (fabric-interop, DEC-0104) ---
+
+
+def job_caller_key(accepted: Any = MISSING, credential: Any = MISSING) -> Optional[str]:
+    """The key of a job's caller at a node that queues (DEC-0104), as the contract's jobCallerKey: for a call whose
+    delegation the node accepted (verify_delegation's answer), its `principal` and `caller` and the partner
+    organization when the chain ends in one (DEC-0090); for a call with no token, the credential the node knows the
+    caller by (a gate's pass with `principal: None` is that case too). A refused verdict has no key, and neither has
+    an unreadable call: None. The key is opaque; only equality matters."""
+    if isinstance(accepted, dict) and not (get(accepted, "ok") is True and get(accepted, "principal") is None):
+        principal, caller = get(accepted, "principal"), get(accepted, "caller")
+        if get(accepted, "ok") is not True or not _string(principal) or principal == "" or not _string(caller) or caller == "":
+            return None
+        chain = get(accepted, "chain")
+        chain = chain if isinstance(chain, list) else []
+        last = chain[-1] if chain else MISSING
+        partner = [last] if len(chain) > 1 and _string(last) and last.startswith("org:") else []
+        return json_stringify(["delegated", principal, caller] + partner)
+    return json_stringify(["credential", credential]) if _string(credential) and credential != "" else None
+
+
+def _limits_ok(limits: Any) -> bool:
+    if not isinstance(limits, dict):
+        return False
+    concurrency, per_caller, queue_max = get(limits, "concurrency"), get(limits, "perCaller"), get(limits, "queueMax")
+    return (all(safe_integer(n) and double(n) >= 1 for n in (concurrency, per_caller))
+            and safe_integer(queue_max) and double(queue_max) >= 0)
+
+
+def _waiting_job(job: Any) -> bool:
+    return isinstance(job, dict) and _string(get(job, "id")) and _string(get(job, "caller")) and math.isfinite(_utc_ms(get(job, "at")))
+
+
+def next_queued_job(queue: Any, running: Any, limits: Any) -> Optional[str]:
+    """The job the hosting node starts next for one (agentRef, context), or None (DEC-0104). Nothing starts while
+    `concurrency` jobs run (every running job holds a slot, its caller readable or not). Of the waiting jobs whose
+    caller runs fewer than `perCaller`, the one whose caller runs the fewest wins; between those callers, the one whose
+    oldest waiting job arrived first; within a caller, its oldest. Arrival ties break by id (UTF-16 order)."""
+    if not _limits_ok(limits):
+        return None
+    if (len(running) if isinstance(running, list) else 0) >= double(limits["concurrency"]):
+        return None
+    running_of: Dict[str, int] = {}
+    for job in objects(running):
+        if _string(get(job, "caller")):
+            running_of[job["caller"]] = running_of.get(job["caller"], 0) + 1
+    waiting = [job for job in objects(queue) if _waiting_job(job) and running_of.get(job["caller"], 0) < double(limits["perCaller"])]
+    waiting.sort(key=lambda job: (_utc_ms(job["at"]), _utf16(job["id"])))
+    best: Optional[Dict[str, Any]] = None
+    for job in waiting:
+        if best is None or running_of.get(job["caller"], 0) < running_of.get(best["caller"], 0):
+            best = job
+    return None if best is None else best["id"]
+
+
+def admit_job(queue: Any, running: Any, job: Any, limits: Any, retry_after_seconds: Any = MISSING) -> Dict[str, Any]:
+    """Whether a start is admitted (DEC-0104): it is when the job would start at once (next_queued_job over the queue
+    with it added answers its id), or when fewer than `queueMax` jobs wait; otherwise {admit: False, error} with the
+    `queue-full` refusal and its `retryAfterSeconds` (1 to 3600, else 60). Unreadable limits or job refuse."""
+    waiting = objects(queue)
+    if _limits_ok(limits) and _waiting_job(job) and (
+            next_queued_job(waiting + [job], running, limits) == job["id"] or len(waiting) < double(limits["queueMax"])):
+        return {"admit": True}
+    after = retry_after_seconds if safe_integer(retry_after_seconds) and 1 <= double(retry_after_seconds) <= 3600 else DEFAULT_RETRY_AFTER_SECONDS
+    return {"admit": False, "error": {"code": _QUEUE_FULL, "message": QUEUE_FULL_MESSAGE,
+                                      "data": {"retryable": True, "retryAfterSeconds": int(after)}}}
+
+
+def queue_status_message(position: Any, length: Any) -> Optional[str]:
+    """The `statusMessage` of a waiting job (DEC-0104): `queued <position> of <length>`, 1 is next, 1 <= position <=
+    length <= 999999; None for anything else."""
+    if not (safe_integer(position) and safe_integer(length)):
+        return None
+    if not 1 <= double(position) <= double(length) <= QUEUE_LENGTH_MAX:
+        return None
+    return "queued %d of %d" % (int(position), int(length))
+
+
+def read_queue_position(status_message: Any) -> Optional[Dict[str, int]]:
+    """A waiting job's place, read from its `statusMessage`, or None when it is not the queue's grammar."""
+    match = _QUEUED.fullmatch(status_message) if _string(status_message) else None
+    if not match:
+        return None
+    position, length = int(match.group(1)), int(match.group(2))
+    return {"position": position, "length": length} if 1 <= position <= length else None
+
+
+def _finding(code: str, instance_path: str, message: str) -> Dict[str, str]:
+    return {"code": code, "instancePath": instance_path, "message": message}
+
+
+def job_queue_rules(value: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-131 on {queue, running, limits, started} (`started`: the id the node started, or None): it is
+    next_queued_job's."""
+    want = next_queued_job(get(value, "queue"), get(value, "running"), get(value, "limits"))
+    started = get(value, "started")
+    if same(None if started is MISSING else started, want):
+        return []
+    return [_finding("FAC-SEM-131", "/started", "nothing may start now" if want is None else "the job to start is %s" % show(want))]
+
+
+# --- The load report (DEC-0104) ---
+
+
+def load_report_rules(report: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-132 on a `service-load/1` report: windows in order one `windowSeconds` apart, none after `generatedAt`,
+    one row per context, p50 at most p95, a run time only where a job ended."""
+    findings: List[Dict[str, str]] = []
+    flag = lambda path, message: findings.append(_finding("FAC-SEM-132", path, message))  # noqa: E731
+    seconds = get(report, "windowSeconds")
+    step = double(seconds) * 1000 if safe_integer(seconds) else math.nan
+    generated = _strict_ms(get(report, "generatedAt"))
+    previous: Any = MISSING
+    for index, window in enumerate(objects(get(report, "windows"))):
+        start = _strict_ms(get(window, "start"))
+        if start > generated:
+            flag("/windows/%d/start" % index, "a window starts after the report was generated")
+        if previous is not MISSING and start - previous != step:
+            flag("/windows/%d/start" % index, "windows are not in order one windowSeconds apart")
+        previous = start
+        seen = set()
+        for at, row in enumerate(objects(get(window, "byContext"))):
+            path = "/windows/%d/byContext/%d" % (index, at)
+            context = get(row, "context")
+            if _string(context) and context in seen:
+                flag(path + "/context", "context %s appears twice in one window" % show(context))
+            if _string(context):
+                seen.add(context)
+            for name in ("waitMs", "runMs"):
+                pct = get(row, name)
+                p50, p95 = get(pct, "p50"), get(pct, "p95")
+                if isinstance(pct, dict) and is_number(p50) and is_number(p95) and double(p50) > double(p95):
+                    flag("%s/%s" % (path, name), "p50 is above p95")
+            if isinstance(get(row, "runMs"), dict) and same(get(row, "completed"), 0) and same(get(row, "failed"), 0):
+                flag(path + "/runMs", "a run time with no job ended in the window")
+    return findings
+
+
+def _integer(value: Any, low: float, high: Optional[float], at: str, errors: List[str]) -> None:
+    """JSON Schema's integer with its bounds, as ajv reads it: a number with no fraction (2.0 is one), never a bool."""
+    if not is_number(value) or not math.isfinite(double(value)) or double(value) != math.floor(double(value)):
+        errors.append("%s type" % at)
+    elif double(value) < low:
+        errors.append("%s minimum" % at)
+    elif high is not None and double(value) > high:
+        errors.append("%s maximum" % at)
+
+
+def _members(value: Dict[str, Any], allowed: tuple, required: tuple, at: str, errors: List[str]) -> None:
+    errors.extend("%s/%s additionalProperties" % (at, key) for key in value if key not in allowed)
+    errors.extend("%s required %s" % (at or "/", key) for key in required if key not in value)
+
+
+def _timestamp(value: Any, at: str, errors: List[str]) -> None:
+    if not _string(value):
+        errors.append("%s type" % at)
+    elif not date_time(value):
+        errors.append("%s format" % at)
+
+
+def _percentiles(value: Any, at: str, errors: List[str]) -> None:
+    if not isinstance(value, dict):
+        errors.append("%s type" % at)
+        return
+    _members(value, ("p50", "p95"), ("p50", "p95"), at, errors)
+    for name in ("p50", "p95"):
+        if name in value:
+            _integer(value[name], 0, None, "%s/%s" % (at, name), errors)
+
+
+def _row_problems(row: Any, at: str, errors: List[str]) -> None:
+    if not isinstance(row, dict):
+        errors.append("%s type" % at)
+        return
+    _members(row, ("context",) + _ROW_COUNTS + ("waitMs", "runMs"), ("context",) + _ROW_COUNTS, at, errors)
+    if "context" in row and not (_string(row["context"]) and _CONTEXT.fullmatch(row["context"])):
+        errors.append("%s/context %s" % (at, "pattern" if _string(row["context"]) else "type"))
+    for name in _ROW_COUNTS:
+        if name in row:
+            _integer(row[name], 0, None, "%s/%s" % (at, name), errors)
+    for name in ("waitMs", "runMs"):
+        if name in row:
+            _percentiles(row[name], "%s/%s" % (at, name), errors)
+
+
+def load_report_problems(report: Any) -> List[str]:
+    """service-load.schema.json: what makes `report` not a `service-load/1` report, each as `<path> <keyword>`; empty
+    for a valid one. Counts and durations only: a member the schema does not name (a caller, a job id) is refused."""
+    if not isinstance(report, dict):
+        return ["/ type"]
+    errors: List[str] = []
+    _members(report, ("type", "generatedAt", "windowSeconds", "windows"), ("type", "generatedAt", "windowSeconds", "windows"), "", errors)
+    if "type" in report and not same(report["type"], LOAD_REPORT_TYPE):
+        errors.append("/type const")
+    if "generatedAt" in report:
+        _timestamp(report["generatedAt"], "/generatedAt", errors)
+    if "windowSeconds" in report:
+        _integer(report["windowSeconds"], 60, 86400, "/windowSeconds", errors)
+    windows = report.get("windows", MISSING)
+    if windows is not MISSING and not isinstance(windows, list):
+        errors.append("/windows type")
+    elif isinstance(windows, list):
+        if len(windows) > 168:
+            errors.append("/windows maxItems")
+        for index, window in enumerate(windows):
+            at = "/windows/%d" % index
+            if not isinstance(window, dict):
+                errors.append("%s type" % at)
+                continue
+            _members(window, ("start", "byContext"), ("start", "byContext"), at, errors)
+            if "start" in window:
+                _timestamp(window["start"], at + "/start", errors)
+            rows = window.get("byContext", MISSING)
+            if rows is not MISSING and not isinstance(rows, list):
+                errors.append("%s/byContext type" % at)
+            elif isinstance(rows, list):
+                if len(rows) > 64:
+                    errors.append("%s/byContext maxItems" % at)
+                for row_index, row in enumerate(rows):
+                    _row_problems(row, "%s/byContext/%d" % (at, row_index), errors)
+    return errors
+
+
+def _declaration_problems(value: Any) -> List[str]:
+    """service-load-extension.schema.json, each problem as `<path> <keyword>`; empty for a valid declaration."""
+    if not isinstance(value, dict):
+        return ["/ type"]
+    errors: List[str] = []
+    _members(value, ("path", "windowSeconds", "limits"), ("path", "windowSeconds", "limits"), "", errors)
+    path = value.get("path", MISSING)
+    if path is not MISSING:
+        if not _string(path):
+            errors.append("/path type")
+        else:
+            if len(path) > 256:  # code points, as ajv counts them; the originPath's own 2048 is wider
+                errors.append("/path maxLength")
+            if not _ORIGIN_PATH.fullmatch(path):
+                errors.append("/path pattern")
+    if "windowSeconds" in value:
+        _integer(value["windowSeconds"], 60, 86400, "/windowSeconds", errors)
+    limits = value.get("limits", MISSING)
+    if limits is not MISSING:
+        if not isinstance(limits, dict):
+            errors.append("/limits type")
+        else:
+            _members(limits, tuple(name for name, _, _ in _LIMITS), tuple(name for name, _, _ in _LIMITS), "/limits", errors)
+            for name, low, high in _LIMITS:
+                if name in limits:
+                    _integer(limits[name], low, high, "/limits/%s" % name, errors)
+    return errors
+
+
+def load_view(well_known: Any) -> Dict[str, Any]:
+    """The load declaration as a reader reads it (DEC-0104): `declared` when the extension key is present, `valid` when
+    its value is the schema's, `load` the declaration when valid (else None) and `errors` its problems. A reader treats
+    an invalid value as not declared and reports it (FAC-SEM-133)."""
+    extensions = get(well_known, "extensions")
+    if not isinstance(extensions, dict) or LOAD_EXTENSION_KEY not in extensions:
+        return {"declared": False, "valid": False, "load": None, "errors": []}
+    value = extensions[LOAD_EXTENSION_KEY]
+    errors = _declaration_problems(value)
+    return {"declared": True, "valid": not errors, "load": None if errors else value, "errors": errors}
+
+
+def load_extension_rules(well_known: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-133 on a well-known document: a value under the load extension key is valid against
+    service-load-extension.schema.json; one finding at the key otherwise."""
+    view = load_view(well_known)
+    if not view["declared"] or view["valid"]:
+        return []
+    return [_finding("FAC-SEM-133", _KEY_PATH, "the load declaration is invalid (%s); a reader treats it as not declared "
+                                               "and reports it (DEC-0104)" % "; ".join(view["errors"]))]
+
+
+def load_extension(path: Any, window_seconds: Any, limits: Any) -> Dict[str, Any]:
+    """The `extensions` entry a service declares (DEC-0104): where it serves its `service-load/1` report (an origin
+    path, served under the descriptor token like the usage report), the report's window and the queue's limits per
+    (agentRef, context). Raises ServiceError on a declaration a reader would treat as not declared."""
+    value = {"path": path, "windowSeconds": window_seconds, "limits": dict(limits) if isinstance(limits, dict) else limits}
+    problems = _declaration_problems(value)
+    if problems:
+        raise ServiceError("Load declaration: %s." % "; ".join(problems))
+    return {LOAD_EXTENSION_KEY: value}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_package.py

@@ -700,8 +700,76 @@ def compose(draft: Dict[str, Any], files: Dict[str, bytes]) -> Tuple[Dict[str, A
     return pkg, notes
 
 
+#: The agent's source manifest (contract DEC-0149, ``fabric-source/1``): when the folder carries one, ``pack`` writes
+#: ``secrets[]`` from its secret slots and ``state[]`` from its store slots' paths, and FAC-SEM-160 holds them equal.
+SOURCE_FILE = "fabric.source.json"
+
+
+def _source_manifest(files: Dict[str, bytes]) -> Optional[Dict[str, Any]]:
+    """The folder's source manifest, or None when it has none; a refusal when it is no ``fabric-source/1`` object."""
+    if SOURCE_FILE not in files:
+        return None
+    source = _load_json(files[SOURCE_FILE], SOURCE_FILE)
+    if source.get("format") != "fabric-source/1":
+        raise PackageError("%s is not a fabric-source/1 manifest (its format member)." % SOURCE_FILE)
+    return source
+
+
+def source_members(source: Dict[str, Any]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """``secrets[]`` from the secret slots (name, purpose, optional) and ``state[]`` from the store slots (path, purpose)."""
+    secrets: List[Dict[str, Any]] = []
+    state: List[Dict[str, Any]] = []
+    for slot in _objects(source.get("slots")):
+        if slot.get("kind") == "secret" and isinstance(slot.get("name"), str):
+            secrets.append(dict({"name": slot["name"], "purpose": slot.get("purpose")}, **({"optional": True} if slot.get("optional") is True else {})))
+        elif slot.get("kind") == "store" and isinstance(slot.get("path"), str):
+            state.append({"path": slot["path"], "purpose": slot.get("purpose")})
+    return secrets, state
+
+
+def source_package_findings(source: Any, pkg: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-160 (contract ``sourcePackageFindings``): the package's secrets[] are the source's secret slots, by name
+    and optional; its state[] paths are the store slots' paths when state[] holds any entry."""
+    if not isinstance(source, dict) or not isinstance(pkg, dict):
+        return []
+    out: List[Dict[str, str]] = []
+
+    def flag(at: str, message: str) -> None:
+        out.append({"code": "FAC-SEM-160", "instancePath": at, "message": message})
+    slots = _objects(source.get("slots"))
+    secrets = {s["name"]: s.get("optional") is True for s in slots if s.get("kind") == "secret" and isinstance(s.get("name"), str)}
+    stores = list(dict.fromkeys(s["path"] for s in slots if s.get("kind") == "store" and isinstance(s.get("path"), str)))
+    packaged = [(e, i) for i, e in enumerate(pkg.get("secrets") if isinstance(pkg.get("secrets"), list) else []) if isinstance(e, dict)]
+    names = {e.get("name") for e, _ in packaged}
+    for name in secrets:
+        if name not in names:
+            flag("/package/secrets", "the source's secret slot %s is not in the package's secrets[]" % name)
+    for entry, index in packaged:
+        name = entry.get("name")
+        if not isinstance(name, str) or name not in secrets:
+            flag("/package/secrets/%d/name" % index, "secrets[%d] is no secret slot of the source" % index)
+        elif secrets[name] != (entry.get("optional") is True):
+            flag("/package/secrets/%d/optional" % index, "secrets[%d] is %soptional in the source" % (index, "" if secrets[name] else "not "))
+    state = pkg.get("state")
+    if not isinstance(state, list) or not state:
+        return out
+    paths = {e.get("path") for e in _objects(state)}
+    for path in stores:
+        if path not in paths:
+            flag("/package/state", "a store slot's path of the source is not in the package's state[]")
+    for index, entry in ((i, e) for i, e in enumerate(state) if isinstance(e, dict)):
+        if not isinstance(entry.get("path"), str) or entry["path"] not in stores:
+            flag("/package/state/%d/path" % index, "state[%d] is no store slot of the source" % index)
+    return out
+
+
 def _all_problems(pkg: Dict[str, Any], files: Dict[str, bytes]) -> List[Dict[str, str]]:
     problems = [dict(p, rule="schema") for p in schema_problems(pkg)]
+    if SOURCE_FILE in files:
+        try:
+            problems += [dict(p, rule=p["code"]) for p in source_package_findings(_source_manifest(files), pkg)]
+        except PackageError as exc:
+            problems.append({"rule": "source", "instancePath": "/files", "message": str(exc)})
     problems += [dict(p, rule="path") for p in path_problems(pkg)]
     problems += [dict(p, rule=p["code"]) for p in package_findings(pkg)]
     problems += [{"rule": "folder", "problem": p["problem"], "instancePath": p["path"], "message": FOLDER_MESSAGES.get(p["problem"], p["problem"])}
@@ -716,6 +784,24 @@ FOLDER_MESSAGES = {
 }
 
 
+def _secrets_lacking(draft: Dict[str, Any], secrets: List[Dict[str, Any]]) -> List[str]:
+    """The names a hand-written secrets[] declares that the source manifest has no secret slot for, in their order."""
+    have = {s["name"] for s in secrets}
+    declared = draft.get("secrets") if isinstance(draft.get("secrets"), list) else []
+    lacking: List[str] = []
+    for entry in declared:
+        name = entry.get("name") if isinstance(entry, dict) else None
+        if isinstance(name, str) and name not in have and name not in lacking:
+            lacking.append(name)
+    return lacking
+
+
+def _lacking_message(lacking: List[str]) -> str:
+    return ("%s declares no secret slot for %s, which %s's secrets[] names: pack writes secrets[] from the manifest's "
+            "slots and never drops a declared secret. Add each as a slot of kind secret to %s (or take it out of "
+            "secrets[]), then pack again" % (SOURCE_FILE, ", ".join(lacking), PACKAGE_FILE, SOURCE_FILE))
+
+
 def pack(folder: Any, apply: bool = False) -> Dict[str, Any]:
     """Pack ``folder`` (see the module's doc). The answer names the digest, ``agentRef`` and every problem; with
     ``apply`` and no problem, ``fabric.package.json`` is rewritten."""
@@ -725,8 +811,24 @@ def pack(folder: Any, apply: bool = False) -> Dict[str, Any]:
         raise PackageError("Write %s in the folder first: schema, kind, id, version, publisher, licence and, for an agent, "
                            "resultSignal and evals with its receipt. pack fills in agentRef, files[] and digest." % PACKAGE_FILE)
     draft = _load_json(files[PACKAGE_FILE], PACKAGE_FILE)
+    source = _source_manifest(files)
+    written: List[str] = []
+    refused: List[Dict[str, str]] = []
+    if source is not None:  # DEC-0149: secrets[] and state[] come from the source manifest's slots
+        secrets, state = source_members(source)
+        lacking = _secrets_lacking(draft, secrets)
+        if lacking:  # a declared secret is never dropped: the manifest gains its slot first
+            refused.append({"rule": "source", "instancePath": "/secrets", "message": _lacking_message(lacking)})
+        elif secrets or "secrets" in draft:
+            draft["secrets"] = secrets
+            written.append("secrets[]")
+        if state and draft.get("state") != []:  # an empty state[] is a copy packed without state, kept
+            draft["state"] = state
+            written.append("state[]")
     pkg, notes = compose(draft, files)
-    problems = _all_problems(pkg, files)
+    if written:
+        notes.append("%s written from %s" % (" and ".join(written), SOURCE_FILE))
+    problems = refused + _all_problems(pkg, files)
     suite = pkg.get("evals", {}).get("suite") if isinstance(pkg.get("evals"), dict) else None
     if isinstance(suite, str) and suite in files and any(p.get("instancePath") == "/evals/receipt/suite" for p in problems):
         notes.append("the suite packed is %s: run it again and write that receipt" % sha256_of(files[suite]))

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_peer_owner.py

@@ -1,8 +1,11 @@
 """peer_owner: which OS account owns each end of a loopback TCP connection.
 
-    peer_owner 1.1.0+kit.3: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
-    DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py` at
-    commit f86f0622 (passioncode-ai/project-observatory-dashboard, the same licence). It differs
+    peer_owner 1.2.0+kit.5: Observatory's peer_owner 1.2.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
+    DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py`, first at
+    commit f86f0622 (1.1.0) and read against commit 2180235c (1.2.0, passioncode-ai/project-observatory-dashboard, the
+    same licence): the kit's line names 1.2.0 since kit.5 (FAA-258), whose Linux rule kit.1 to kit.4 already carried
+    and the contract's CT-254 states (v0.1.0+2026-11-07.3). Observatory's 1.3.x (this account's own sockets through
+    libproc, the contract's DEC-0155 RT-2) is not in it yet (FAA-292). It differs
     from that file in this paragraph, in `Owner` and `Row` (NamedTuples here where it has
     frozen dataclasses: a dataclass with postponed annotations needs its module in sys.modules,
     and a service may load a kit file by its path without one), and in writing `Optional[X]`
@@ -11,7 +14,8 @@
     SID before the system's (a client running as root or SYSTEM owns root's listener), and in
     two Linux and selection rules: on Linux `server_end` reads an accepted connection's own row
     and, for one not accept()ed yet (printed with uid 0 and inode 0), the listener row on its
-    local address (state 0A; Observatory's 1.2.0 reading), `peer` reads a client
+    local address (state 0A; 1.2.0's rule, where the kit names its reasons `not-accepted`, `several-rows` and `closed`
+    and Observatory `no-listener`, `listener-no-socket`, `listeners-disagree` and `no-socket`), `peer` reads a client
     row with inode 0 (a closed client) as unknown, and several rows of one owner are that owner;
     a row printed twice by a `/proc` read under churn counts once, and a `/proc` question that
     finds no row or several reads the table once more; ctypes is imported where it is used, so a
@@ -19,7 +23,8 @@
     macOS: the sysctl calibration also requires a child process's listener, an empty netstat reads as
     `TABLE_RESTRICTED`, and a caller may vouch for a listener with a pid it started (`pid_listens`,
     `parse_lsof_listeners`, `LSOF`, `CheckedHTTPConnection(vouch_pid=...)`, `own_connection(vouch_pid=...)`); since kit.3
-    the child's port is waited on with `selectors` and read under one deadline (FAA-273).
+    the child's port is waited on with `selectors` and read under one deadline (FAA-273); since kit.4 a number is ASCII
+    digits only and a netstat with only its header reads as `TABLE_RESTRICTED` (FAA-273 items 3 and 4).
     A limit /proc sets: it carries a socket's creator and no pid, so a listening socket that root
     created and handed to another account (systemd socket activation with User=) reads as root's. Standard library only, no import of another kit module.
     The kit's tests are `test/test_fabric_peer_owner.py`, over `test/fixtures/peer-owner/`;
@@ -110,7 +115,7 @@ import time
 from typing import NamedTuple, Optional, Tuple
 
 # This file's own version, for projects that copy it; not the engine's (that is configuration.VERSION).
-PEER_OWNER_VERSION = "1.1.0+kit.3"  # Observatory's 1.1.0 with the kit's differences above
+PEER_OWNER_VERSION = "1.2.0+kit.5"  # Observatory's 1.2.0 with the kit's differences above
 
 THIS_ACCOUNT = "this-account"
 ANOTHER_ACCOUNT = "another-account"
@@ -121,7 +126,8 @@ KINDS = (THIS_ACCOUNT, ANOTHER_ACCOUNT, SYSTEM, UNKNOWN, NONE)
 
 #: The most table bytes one read accepts. The spec of this module asked for 1 MB; measured,
 #: `pcblist_n` costs about 860 bytes a socket, so 1 MB would hold about 1,200 sockets and a busy
-#: developer machine passes that. 4 MiB holds about 4,800.
+#: developer machine passes that. 4 MiB holds about 6,800 at the 616 bytes a socket measured on macOS 26
+#: (0.74.0 product reading 11, FAA-260).
 MAX_TABLE_BYTES = 4 * 1024 * 1024
 #: Every subprocess this module starts is stopped after this many seconds.
 TIMEOUT_SECONDS = 2.0
@@ -231,6 +237,11 @@ def classify(uid: Optional[int], pid: Optional[int], *, method: str, own_uid: Op
 
 # -- parsers: pure functions over captured text or bytes (the tests' fixtures) ---------------------------------------
 
+def _ascii_digits(text: str) -> bool:
+    """`[0-9]+` as the Node twin reads a number; `str.isdigit` also takes `٤` and `²` (FAA-273 item 4)."""
+    return text != "" and text.isascii() and text.isdigit()
+
+
 def parse_netstat(text: str) -> list[Row]:
     """`netstat -anv -p tcp` on macOS. Process names may hold spaces ("Some App:123"), so the
     `process:pid` column is what is left between the leading and the trailing columns, both
@@ -246,6 +257,10 @@ def parse_netstat(text: str) -> list[Row]:
     # "Local Address" and "Foreign Address" are two header words each and one data column each.
     leading = at - sum(1 for w in names[:at] if w == "Address")
     trailing = len(names) - at - 1
+    if not any(line.split()[:1] and line.split()[0].startswith("tcp") for line in lines[header + 1:]):
+        # The caller's own connection is in any table it can see: a header and no tcp row is the restricted table
+        # (FAA-273 item 3), not `no-row`.
+        raise TableUnreadable(f"{TABLE_RESTRICTED}: netstat printed only its header to this process")
     rows: list[Row] = []
     for line in lines[header + 1:]:
         tok = line.split()
@@ -259,7 +274,7 @@ def parse_netstat(text: str) -> list[Row]:
         pid = None
         if ":" in process:
             tail = process.rsplit(":", 1)[1]
-            pid = int(tail) if tail.isdigit() else None
+            pid = int(tail) if _ascii_digits(tail) else None
         rows.append(Row(local, remote, tok[5] == "LISTEN", None, pid, tok[5] == "TIME_WAIT"))
     return rows
 
@@ -283,7 +298,7 @@ def parse_lsof_listeners(text: str) -> list[tuple[str, int]]:
         if not line.startswith("n") or ":" not in line:
             continue
         host, port = line[1:].rsplit(":", 1)
-        if port.isdigit():
+        if _ascii_digits(port):
             found.append((norm_host(host.strip("[]")), int(port)))
     return found
 
@@ -291,7 +306,7 @@ def parse_lsof_listeners(text: str) -> list[tuple[str, int]]:
 def parse_ps_uid(text: str) -> Optional[int]:
     """`ps -o uid= -p PID`: one number, or nothing when the process is gone."""
     text = text.strip()
-    return int(text) if text.isdigit() else None
+    return int(text) if _ascii_digits(text) else None
 
 
 def parse_proc_net_tcp(text: str, *, family: int, byteorder: Optional[str] = None) -> list[Row]:
@@ -540,7 +555,7 @@ def _child_listener_seen(rows_of) -> Optional[bool]:
     port = None
     try:
         line = _child_line(child, deadline)
-        if line is None or not line.strip().isdigit():
+        if line is None or not _ascii_digits(line.strip()):
             return None
         port = int(line.strip())
         try:
@@ -794,7 +809,7 @@ def _owner_of(local: tuple[str, int], remote: tuple[str, int], server: bool = Fa
         # (inet_csk_listen_stop), so that listener answers. An accepted connection's own row carries the uid of the
         # process that accepted it (sock_graft): it answers itself, so a listener swapped after another account
         # accepted the client cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's
-        # pending CT-254, FAA-258).
+        # CT-254, HA-2's Linux source, released in v0.1.0+2026-11-07.3).
         # A server row its owner already closed (an orphan) also has inode 0 and reads so: no process holds it, so
         # nothing sent to it reaches anyone (0.74.0 unit reading 6).
         return _one_owner(_listeners_of(rows, found[0].local), how, "not-accepted")
@@ -846,7 +861,7 @@ def server_end(sock: socket.socket) -> Owner:
     server's and whose remote address is this socket's own, which is the server process's
     accepted socket, so a listener swapped after `listen` cannot pass for the one that answers.
     On Linux a connection not yet accept()ed has no owner of its own (inode 0): its listener
-    answers (the contract's pending CT-254, FAA-258)."""
+    answers (the contract's CT-254, HA-2's Linux source)."""
     try:
         own, server = sock.getsockname(), sock.getpeername()
     except OSError as exc:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_protocols.py

@@ -20,7 +20,7 @@ PROTOCOL_REVISIONS: Dict[str, Tuple[str, ...]] = {
     "fabric-operator-channel": ("0.1",), "fabric-package": ("1",),
     "fabric-peer-share": ("1",), "fabric-peer-share-envelope": ("1",), "fabric-peer-share-report": ("1",), "fabric-project-comms": ("0.1",), "fabric-proposal": ("1",),
     "fabric-provider": ("0.1",), "fabric-relay": ("0.1",), "fabric-secret-envelope": ("1",), "fabric-service": ("0.1",),
-    "fabric-settings-backup": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "machine-report": ("1",), "mandate": ("1",), "memory": ("0.1",), "node-summary": ("1",),
+    "fabric-settings-backup": ("1",), "fabric-source": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "machine-report": ("1",), "mandate": ("1",), "memory": ("0.1",), "node-summary": ("1",),
     "operator-source": ("1",), "org-adaptation": ("1",), "org-adaptation-receipt": ("1",), "org-authority": ("1",), "org-authority-draft": ("1",), "org-key-set": ("1",), "org-key-set-draft": ("1",),
     "org-membership": ("1",), "org-root-registration": ("1",), "pairing-message": ("1",),
     "peer-share-deletion": ("1",), "peer-share-frame": ("1",), "peer-share-revocation": ("1",),