@anthusai/papyrus 5.35.0 → 5.37.0

package/amplify/plugins/reader-steering/function/handler.py

@@ -1015,15 +1015,22 @@ class DynamoReaderStore:
             raise
         return True
 
-    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str) -> bool:
+    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str, *, expected_updated_at: str | None = None) -> bool:
+        """Apply ``changes`` if the state (and, when given, ``updatedAt``) is still what the caller saw; a value of ``None`` removes the attribute."""
         names = {"#st": "state", "#u": "updatedAt", **{f"#c{index}": key for index, key in enumerate(changes)}}
-        assignments = ", ".join(f"#c{index} = :c{index}" for index in range(len(changes)))
-        values = {":expected": expected_state, ":now": now_iso, **{f":c{index}": value for index, value in enumerate(changes.values())}}
+        sets = ", ".join(f"#c{index} = :c{index}" for index, value in enumerate(changes.values()) if value is not None)
+        removes = ", ".join(f"#c{index}" for index, value in enumerate(changes.values()) if value is None)
+        values = {":expected": expected_state, ":now": now_iso, **{f":c{index}": value for index, value in enumerate(changes.values()) if value is not None}}
+        condition = "#st = :expected"
+        if expected_updated_at is not None:
+            condition += " AND #u = :seen"
+            values[":seen"] = expected_updated_at
+        expression = f"SET {sets + ', ' if sets else ''}#u = :now" + (f" REMOVE {removes}" if removes else "")
         try:
             self._table("proposal").update_item(
                 Key={"id": proposal_id},
-                UpdateExpression=f"SET {assignments}, #u = :now",
-                ConditionExpression="#st = :expected",
+                UpdateExpression=expression,
+                ConditionExpression=condition,
                 ExpressionAttributeNames=names,
                 ExpressionAttributeValues=values,
             )
@@ -1499,10 +1506,10 @@ def run_ai_worker(
     return result
 
 
-def handle_staff_event(event: dict[str, Any], *, store: Any, settings: ReaderSettings, now_seconds: float) -> dict[str, Any]:
+def handle_staff_event(event: dict[str, Any], *, store: Any, settings: ReaderSettings, now_seconds: float, account_id: str | None = None) -> dict[str, Any]:
     """``moderateReader`` from AppSync: an editor or admin hides, approves, promotes, bans or undoes. Answers a receipt, never an exception."""
-    if (event.get("info") or {}).get("fieldName") in proposal_rules.MUTATIONS:
-        return proposal_rules.handle_proposal_event(event, store, now_iso=iso(now_seconds))
+    if proposal_rules.event_field_name(event) in proposal_rules.MUTATIONS:
+        return proposal_rules.handle_proposal_event(event, store, now_iso=iso(now_seconds), account_id=account_id)
     identity = event.get("identity") or {}
     claims = identity.get("claims") or {}
     groups = claims.get("cognito:groups") or identity.get("groups") or []
@@ -1527,14 +1534,20 @@ def handle_staff_event(event: dict[str, Any], *, store: Any, settings: ReaderSet
     return outcome.to_dict()
 
 
+def function_account(context: Any) -> str | None:
+    """The AWS account this function runs in, from its own ARN: the only account whose IAM operators may file proposals."""
+    parts = str(getattr(context, "invoked_function_arn", None) or "").split(":")
+    return parts[4] if len(parts) > 4 and parts[4] else None
+
+
 def handler(event: dict[str, Any], _context: Any = None) -> dict[str, Any]:
     import boto3
 
     settings = settings_from_environment()
     store = store_from_environment()
     now_seconds = time.time()
-    if "arguments" in event and "info" in event:
-        return handle_staff_event(event, store=store, settings=settings, now_seconds=now_seconds)
+    if proposal_rules.is_appsync_event(event):
+        return handle_staff_event(event, store=store, settings=settings, now_seconds=now_seconds, account_id=function_account(_context))
     target = snapshot_target_from_environment()
     if settings.moderation_mode == "ai" and target is not None and _context is not None:
         if event.get("worker") == AI_WORKER:

package/amplify/plugins/reader-steering/function/proposals.py

@@ -3,7 +3,10 @@
 A proposal is a change to the map written down where readers can see it: a story draft, a new concept, a rename, a merge,
 a split, a new column or an element symbol. It is filed by AI (a reader proposer is part of the record but has no route yet)
 and steered by votes; an editor decides. Staff reach this through the ``fileProposal`` and ``transitionProposal``
-mutations (editors and admins only; the function checks the groups again). Every state change is appended to the proposal's
+mutations (editors and admins; the function checks the groups again). An operator's IAM role in the function's own account
+(an unattended automation or an agent without a browser sign-in) may also file an AI proposal and move it from draft to
+in_steering or declined, and nothing else: approving, deciding after review and overriding stay with editors and admins.
+``editProposal`` is the editor tier (pin, hold, exclude and restore votes): editors and admins only, never an operator. Every state change is appended to the proposal's
 ``history`` in the same conditional write that changes the state, so the history and the state cannot disagree.
 
 Nothing here knows a person id. The proposer is ``"ai"`` or a reader's siteSubject, which is stored and never published; the
@@ -53,9 +56,41 @@ TARGET_COUNTS: dict[str, tuple[int, int]] = {
 }
 TARGET_TYPES = ("concept", "entity", "column", "story", "cluster")
 
-MUTATIONS = ("fileProposal", "transitionProposal")
+MUTATIONS = ("fileProposal", "transitionProposal", "editProposal")
+
+#: What ``editProposal`` does beyond moving the state. Editors and admins only: an operator is refused every one of them.
+PIN, UNPIN, HOLD, RELEASE, EXCLUDE_VOTES, UNDO_EXCLUSION = "pin", "unpin", "hold", "release", "exclude_votes", "undo_exclusion"
+EDIT_ACTIONS = (PIN, UNPIN, HOLD, RELEASE, EXCLUDE_VOTES, UNDO_EXCLUSION)
+FINAL_STATES = (APPROVED, DECLINED, OVERRIDDEN_BY_EDITOR)
+#: The batch rules for excluding votes. A rule excludes the votes on one proposal that were already cast, by accounts that were
+#: younger than ``hours`` when they voted; the snapshot applies it (votes are not counted here). ``label`` is the public wording.
+EXCLUSION_RULES: dict[str, dict[str, Any]] = {
+    "new-accounts-24h": {"hours": 24, "label": "accounts under 24 h"},
+}
+EXCLUSION_ID = re.compile(r"exc-[0-9a-f]{12}")
+MAXIMUM_EDITOR_LOG = 200
+
+
+def event_field_name(event: dict[str, Any]) -> str | None:
+    """The GraphQL field an AppSync invocation is for.
+
+    The Amplify Gen 2 Lambda data source sends ``fieldName`` at the top level with no ``info`` key; a direct resolver nests it
+    under ``info``. Accept both.
+    """
+    info = event.get("info")
+    name = (info.get("fieldName") if isinstance(info, dict) else None) or event.get("fieldName")
+    return name if isinstance(name, str) and name else None
+
+
+def is_appsync_event(event: dict[str, Any]) -> bool:
+    """True for an AppSync invocation (arguments plus ``info`` or a top-level ``fieldName``); the public path sends siteSubject, action and payload."""
+    return "arguments" in event and ("info" in event or event_field_name(event) is not None)
 PROPOSER_AI = "ai"
 STAFF_GROUPS = frozenset({"editor", "admin"})
+#: The only moves an operator's IAM role may make, as (from, to). Everything after the draft is an editor's decision.
+OPERATOR_TRANSITIONS = frozenset({(DRAFT, IN_STEERING), (DRAFT, DECLINED)})
+BY_STAFF, BY_OPERATOR = "staff", "operator"
+MAXIMUM_OPERATOR_LABEL = 256
 PROPOSAL_ID = re.compile(r"prop-[0-9a-f]{32}")
 TARGET_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:\-]{0,127}")
 MAXIMUM_TITLE = 200
@@ -86,7 +121,7 @@ class ProposalStore(Protocol):
 
     def create_proposal(self, row: dict[str, Any]) -> bool: ...
 
-    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str) -> bool: ...
+    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str, *, expected_updated_at: str | None = None) -> bool: ...
 
 
 def staff_subject(identity: dict[str, Any]) -> str | None:
@@ -101,6 +136,24 @@ def staff_subject(identity: dict[str, Any]) -> str | None:
     return subject
 
 
+def operator_actor(identity: dict[str, Any], account_id: str | None) -> str | None:
+    """``operator:<principal ARN>`` for an IAM principal (a role or user) of the function's own account, or ``None``.
+
+    A Cognito identity-pool user is also an IAM principal of this account, but it carries a Cognito identity id (and a
+    user-pool caller carries a subject); neither is an operator. A principal of another account is refused, and so is a
+    caller whose ARN names another account than the one AppSync reports.
+    """
+    if not isinstance(identity, dict) or not account_id:
+        return None
+    arn = identity.get("userArn")
+    parts = arn.split(":") if isinstance(arn, str) else []
+    if len(parts) < 6 or parts[0] != "arn" or parts[4] != account_id or identity.get("accountId") != account_id:
+        return None
+    if any(identity.get(key) for key in ("cognitoIdentityId", "cognitoIdentityPoolId", "cognitoIdentityAuthType", "sub", "claims")):
+        return None
+    return f"operator:{arn}"[:MAXIMUM_OPERATOR_LABEL]
+
+
 def clean_text(value: Any, limit: int) -> str | None:
     if not isinstance(value, str):
         return None
@@ -190,13 +243,15 @@ def file_proposal(arguments: dict[str, Any], *, actor_sub: str, now_iso: str, pr
     return row, None
 
 
-def transition_plan(row: dict[str, Any], to_state: Any, reason: Any, *, actor_sub: str, now_iso: str, result: Any = None) -> dict[str, Any] | Outcome:
+def transition_plan(row: dict[str, Any], to_state: Any, reason: Any, *, actor_sub: str, now_iso: str, result: Any = None, by: str = BY_STAFF) -> dict[str, Any] | Outcome:
     """The changes that move ``row`` to ``to_state``, or why it may not move."""
     state = row.get("state")
     if to_state not in STATES:
         return refused("invalid_state", f"state must be one of {', '.join(STATES)}.")
     if to_state not in TRANSITIONS.get(state, ()):
         return refused("transition_not_allowed", f"A proposal in {state} cannot move to {to_state}.")
+    if row.get("held"):
+        return refused("proposal_held", "That proposal is on hold. Release it before it moves.")
     text = None
     if reason is not None and str(reason).strip():
         text = clean_text(reason, MAXIMUM_REASON)
@@ -209,20 +264,38 @@ def transition_plan(row: dict[str, Any], to_state: Any, reason: Any, *, actor_su
             return refused("result_required", f"An override says what the editor decided: {' or '.join(OVERRIDE_RESULTS)}.")
     elif result is not None:
         return refused("result_not_allowed", "Only an override carries a result; approve and decline are their own.")
-    entry = {"from": state, "to": to_state, "by": "staff", "actor": actor_sub, "reason": text, "at": now_iso}
+    entry = {"from": state, "to": to_state, "by": by, "actor": actor_sub, "reason": text, "at": now_iso}
     if result is not None:
         entry["result"] = result
     history = [*(parse_json(row.get("history")) or []), entry]
-    return {"state": to_state, "history": json.dumps(history)}
-
-
-def apply_transition(store: ProposalStore, *, proposal_id: Any, to_state: Any, reason: Any, actor_sub: str, now_iso: str, result: Any = None) -> Outcome:
+    changes: dict[str, Any] = {"state": to_state, "history": json.dumps(history)}
+    if to_state == OVERRIDDEN_BY_EDITOR:
+        # Stored on the proposal beside the community result, which stays as it was: readers see both.
+        changes["override"] = json.dumps({"result": result, "reason": text, "at": now_iso})
+    return changes
+
+
+def apply_transition(
+    store: ProposalStore,
+    *,
+    proposal_id: Any,
+    to_state: Any,
+    reason: Any,
+    actor_sub: str,
+    now_iso: str,
+    result: Any = None,
+    by: str = BY_STAFF,
+    allowed: frozenset[tuple[str, str]] | None = None,
+) -> Outcome:
+    """Move a proposal. ``allowed`` (as (from, to) pairs) narrows the road for a caller who may not take all of it."""
     if not isinstance(proposal_id, str) or not PROPOSAL_ID.fullmatch(proposal_id):
         return refused("invalid_proposal", "That is not a proposal id.")
     row = store.get_proposal(proposal_id)
     if row is None:
         return refused("not_found", "There is no such proposal.")
-    plan = transition_plan(row, to_state, reason, actor_sub=actor_sub, now_iso=now_iso, result=result)
+    if allowed is not None and (row.get("state"), to_state) not in allowed:
+        return refused("operator_not_allowed", "An operator can only move a draft to in_steering or declined; the rest is for editors and admins.")
+    plan = transition_plan(row, to_state, reason, actor_sub=actor_sub, now_iso=now_iso, result=result, by=by)
     if isinstance(plan, Outcome):
         return plan
     if not store.change_proposal(proposal_id, plan, row["state"], now_iso):
@@ -230,13 +303,101 @@ def apply_transition(store: ProposalStore, *, proposal_id: Any, to_state: Any, r
     return Outcome("ok", id=proposal_id)
 
 
-def handle_proposal_event(event: dict[str, Any], store: ProposalStore, *, now_iso: str) -> dict[str, Any]:
-    """``fileProposal`` or ``transitionProposal`` from AppSync. Answers a receipt, never an exception."""
-    actor = staff_subject(event.get("identity") or {})
+def log_entry(action: str, actor_sub: str, now_iso: str, detail: dict[str, Any] | None = None) -> dict[str, Any]:
+    entry: dict[str, Any] = {"action": action, "by": BY_STAFF, "actor": actor_sub, "at": now_iso}
+    if detail:
+        entry["detail"] = detail
+    return entry
+
+
+def edit_plan(row: dict[str, Any], action: Any, *, rule: Any = None, exclusion_id: Any = None, actor_sub: str, now_iso: str) -> dict[str, Any] | Outcome:
+    """The changes for a pin, hold or vote-exclusion action on ``row``, or why it may not be done.
+
+    Every action is appended to the private ``editorLog`` in the same write. Changing the exclusions clears the frozen
+    ``communityResult`` so the next snapshot fixes it again with the exclusions applied; the function never counts votes itself.
+    """
+    if action not in EDIT_ACTIONS:
+        return refused("invalid_action", f"action must be one of {', '.join(EDIT_ACTIONS)}.")
+    detail: dict[str, Any] | None = None
+    changes: dict[str, Any] = {}
+    if action in (PIN, UNPIN):
+        if bool(row.get("pinned")) == (action == PIN):
+            return refused("already_pinned" if action == PIN else "not_pinned", "That proposal is already pinned." if action == PIN else "That proposal is not pinned.")
+        changes["pinned"] = action == PIN
+    elif action in (HOLD, RELEASE):
+        if action == HOLD and row.get("state") in FINAL_STATES:
+            return refused("proposal_decided", "A decided proposal cannot be put on hold.")
+        if bool(row.get("held")) == (action == HOLD):
+            return refused("already_held" if action == HOLD else "not_held", "That proposal is already on hold." if action == HOLD else "That proposal is not on hold.")
+        changes["held"] = action == HOLD
+    else:
+        exclusions = parse_json(row.get("exclusions")) or []
+        if action == EXCLUDE_VOTES:
+            if rule not in EXCLUSION_RULES:
+                return refused("invalid_rule", f"rule must be one of {', '.join(EXCLUSION_RULES)}.")
+            identifier = "exc-" + uuid.uuid4().hex[:12]
+            exclusions = [*exclusions, {"id": identifier, "rule": rule, "at": now_iso, "actor": actor_sub}]
+            detail = {"exclusion": identifier, "rule": rule}
+        else:
+            if not isinstance(exclusion_id, str) or not EXCLUSION_ID.fullmatch(exclusion_id):
+                return refused("invalid_exclusion", "That is not an exclusion id.")
+            found = next((entry for entry in exclusions if entry.get("id") == exclusion_id), None)
+            if found is None:
+                return refused("unknown_exclusion", "That proposal has no such exclusion.")
+            if found.get("undoneAt"):
+                return refused("already_undone", "That exclusion was already undone.")
+            found["undoneAt"], found["undoneBy"] = now_iso, actor_sub
+            detail = {"exclusion": exclusion_id, "rule": found.get("rule")}
+        changes["exclusions"] = json.dumps(exclusions)
+        if row.get("communityResult"):
+            changes["communityResult"] = None  # removed: the next snapshot fixes it again without the excluded votes
+    log = [*(parse_json(row.get("editorLog")) or []), log_entry(action, actor_sub, now_iso, detail)][-MAXIMUM_EDITOR_LOG:]
+    changes["editorLog"] = json.dumps(log)
+    return changes
+
+
+def apply_edit(store: ProposalStore, *, proposal_id: Any, action: Any, rule: Any, exclusion_id: Any, actor_sub: str, now_iso: str) -> Outcome:
+    if not isinstance(proposal_id, str) or not PROPOSAL_ID.fullmatch(proposal_id):
+        return refused("invalid_proposal", "That is not a proposal id.")
+    row = store.get_proposal(proposal_id)
+    if row is None:
+        return refused("not_found", "There is no such proposal.")
+    plan = edit_plan(row, action, rule=rule, exclusion_id=exclusion_id, actor_sub=actor_sub, now_iso=now_iso)
+    if isinstance(plan, Outcome):
+        return plan
+    if not store.change_proposal(proposal_id, plan, row["state"], now_iso, expected_updated_at=row.get("updatedAt")):
+        return refused("target_changed", "Someone else changed that proposal first.")
+    # An exclusion's id is what undo_exclusion takes; the pin and hold receipts carry the proposal id.
+    created = json.loads(plan["exclusions"])[-1]["id"] if action == EXCLUDE_VOTES else proposal_id
+    return Outcome("ok", id=created)
+
+
+def handle_proposal_event(event: dict[str, Any], store: ProposalStore, *, now_iso: str, account_id: str | None = None) -> dict[str, Any]:
+    """``fileProposal``, ``transitionProposal`` or ``editProposal`` from AppSync. Answers a receipt, never an exception.
+
+    Editors and admins act as themselves. An IAM principal of ``account_id`` (the function's own account) acts as an operator:
+    it files AI proposals and moves draft to in_steering or declined, recorded as ``operator:<ARN>``. Anyone else is refused.
+    """
+    identity = event.get("identity") or {}
+    staff = staff_subject(identity)
+    operator = None if staff is not None else operator_actor(identity, account_id)
+    actor = staff or operator
     if actor is None:
-        return refused("not_staff", "Only editors and admins can file or decide proposals.").to_dict()
+        return refused("not_staff", "Only editors, admins and operators of this account can file proposals; only editors and admins decide them.").to_dict()
     arguments = event.get("arguments") or {}
-    field = (event.get("info") or {}).get("fieldName")
+    field = event_field_name(event)
+    if field == "editProposal":
+        if staff is None:
+            return refused("operator_not_allowed", "Pinning, holding and excluding votes are for editors and admins; an operator can only file proposals and move a draft to in_steering or declined.").to_dict()
+        return apply_edit(
+            store,
+            proposal_id=arguments.get("proposalId"),
+            action=arguments.get("action"),
+            rule=arguments.get("rule"),
+            exclusion_id=arguments.get("exclusionId"),
+            actor_sub=staff,
+            now_iso=now_iso,
+        ).to_dict()
     if field == "fileProposal":
         row, problem = file_proposal(arguments, actor_sub=actor, now_iso=now_iso)
         if problem is not None:
@@ -252,4 +413,6 @@ def handle_proposal_event(event: dict[str, Any], store: ProposalStore, *, now_is
         result=arguments.get("result"),
         actor_sub=actor,
         now_iso=now_iso,
+        by=BY_OPERATOR if operator else BY_STAFF,
+        allowed=OPERATOR_TRANSITIONS if operator else None,
     ).to_dict()

package/amplify/plugins/reader-steering/papyrus.plugin.js

@@ -15,7 +15,7 @@ export const readerSteeringManifest = {
     name: "reader-steering",
     contract: 1,
     models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
-    mutations: ["moderateReader", "fileProposal", "transitionProposal"],
+    mutations: ["moderateReader", "fileProposal", "transitionProposal", "editProposal"],
     guest: { mutations: [] },
     newsroomPanels: [{ id: "moderation", label: "Moderation" }],
     staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],

package/amplify/plugins/reader-steering/papyrus.plugin.ts

@@ -22,7 +22,7 @@ export const readerSteeringManifest: PluginManifest = {
   name: "reader-steering",
   contract: 1,
   models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
-  mutations: ["moderateReader", "fileProposal", "transitionProposal"],
+  mutations: ["moderateReader", "fileProposal", "transitionProposal", "editProposal"],
   guest: { mutations: [] },
   newsroomPanels: [{ id: "moderation", label: "Moderation" }],
   staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],

package/amplify/plugins/reader-steering/schema.js

@@ -148,6 +148,12 @@ export function readerSteeringSchemaDefinitions() {
             state: a.string().required(),
             history: a.json().required(),
             communityResult: a.json(),
+            pinned: a.boolean(),
+            held: a.boolean(),
+            override: a.json(),
+            exclusions: a.json(),
+            editorLog: a.json(),
+            needsLook: a.json(),
             createdAt: a.datetime().required(),
         })
             .disableOperations(["subscriptions"])
@@ -159,6 +165,9 @@ export function readerSteeringSchemaDefinitions() {
             error: a.string(),
             message: a.string(),
         }),
+        // Editors and admins file as themselves. AppSync also admits an IAM principal whose own policy allows the field (the
+        // schema accepts IAM callers for the functions that call it); the function files an AI proposal for an IAM principal
+        // of its own account only, and refuses an identity-pool user and any other account. No IAM rule is declared here.
         fileProposal: a
             .mutation()
             .arguments({
@@ -172,6 +181,8 @@ export function readerSteeringSchemaDefinitions() {
             .returns(a.ref("ProposalReceipt"))
             .authorization((allow) => [allow.group("editor"), allow.group("admin")])
             .handler(functionHandler("readerActions", readerActions)),
+        // The same IAM rule as fileProposal, narrower: an operator may move only draft to in_steering or declined.
+        // Approving, deciding after review and overriding are refused for IAM in the function (`operator_not_allowed`).
         transitionProposal: a
             .mutation()
             .arguments({
@@ -183,6 +194,19 @@ export function readerSteeringSchemaDefinitions() {
             .returns(a.ref("ProposalReceipt"))
             .authorization((allow) => [allow.group("editor"), allow.group("admin")])
             .handler(functionHandler("readerActions", readerActions)),
+        // Editors and admins only, and the function refuses an IAM operator: pin, unpin, hold, release, exclude_votes and
+        // undo_exclusion. `rule` is a batch rule for exclude_votes; `exclusionId` names the exclusion undo_exclusion reverses.
+        editProposal: a
+            .mutation()
+            .arguments({
+            proposalId: a.string().required(),
+            action: a.string().required(),
+            rule: a.string(),
+            exclusionId: a.string(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(functionHandler("readerActions", readerActions)),
         ModerationReceipt: a.customType({
             status: a.string().required(),
             id: a.string(),

package/amplify/plugins/reader-steering/schema.ts

@@ -150,6 +150,12 @@ export function readerSteeringSchemaDefinitions() {
         state: a.string().required(),
         history: a.json().required(),
         communityResult: a.json(),
+        pinned: a.boolean(),
+        held: a.boolean(),
+        override: a.json(),
+        exclusions: a.json(),
+        editorLog: a.json(),
+        needsLook: a.json(),
         createdAt: a.datetime().required(),
       })
       .disableOperations(["subscriptions"])
@@ -161,6 +167,9 @@ export function readerSteeringSchemaDefinitions() {
       error: a.string(),
       message: a.string(),
     }),
+    // Editors and admins file as themselves. AppSync also admits an IAM principal whose own policy allows the field (the
+    // schema accepts IAM callers for the functions that call it); the function files an AI proposal for an IAM principal
+    // of its own account only, and refuses an identity-pool user and any other account. No IAM rule is declared here.
     fileProposal: a
       .mutation()
       .arguments({
@@ -174,6 +183,8 @@ export function readerSteeringSchemaDefinitions() {
       .returns(a.ref("ProposalReceipt"))
       .authorization((allow) => [allow.group("editor"), allow.group("admin")])
       .handler(functionHandler("readerActions", readerActions)),
+    // The same IAM rule as fileProposal, narrower: an operator may move only draft to in_steering or declined.
+    // Approving, deciding after review and overriding are refused for IAM in the function (`operator_not_allowed`).
     transitionProposal: a
       .mutation()
       .arguments({
@@ -185,6 +196,19 @@ export function readerSteeringSchemaDefinitions() {
       .returns(a.ref("ProposalReceipt"))
       .authorization((allow) => [allow.group("editor"), allow.group("admin")])
       .handler(functionHandler("readerActions", readerActions)),
+    // Editors and admins only, and the function refuses an IAM operator: pin, unpin, hold, release, exclude_votes and
+    // undo_exclusion. `rule` is a batch rule for exclude_votes; `exclusionId` names the exclusion undo_exclusion reverses.
+    editProposal: a
+      .mutation()
+      .arguments({
+        proposalId: a.string().required(),
+        action: a.string().required(),
+        rule: a.string(),
+        exclusionId: a.string(),
+      })
+      .returns(a.ref("ProposalReceipt"))
+      .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+      .handler(functionHandler("readerActions", readerActions)),
     ModerationReceipt: a.customType({
       status: a.string().required(),
       id: a.string(),

package/lib/automation-overview.ts

@@ -72,6 +72,10 @@ export type AutomationRecord = {
   enabled: boolean;
   enabledNote: string;
   trigger: { kind: "monitor" | "schedule" | "event" | "manual"; config: Record<string, unknown> };
+  /** Story-stage automations only: the stage that fires it, where the engine moves the story after, and the bot-hop limit. */
+  onStage?: string | null;
+  nextStage?: string | null;
+  maxHops?: number | null;
   supported: boolean;
   supportNote: string | null;
   procedureKey: string;
@@ -106,6 +110,10 @@ export function triggerText(trigger: AutomationRecord["trigger"]): string {
   if (trigger.kind === "monitor") {
     return `${kind} ${String(trigger.config.monitorId ?? "?")}, delivering to ${String(trigger.config.publicationId ?? "?")}`;
   }
+  if (trigger.kind === "event" && trigger.config.event === "story.stage_entered") {
+    const next = trigger.config.nextStage ? `, then moves it to ${String(trigger.config.nextStage)}` : "";
+    return `${kind}: a story enters ${String(trigger.config.onStage ?? "?")}${next}`;
+  }
   return kind;
 }
 

package/lib/prospectus-sign-in-routes.ts

@@ -41,6 +41,8 @@ export interface ProspectusSignInRouteOptions {
   nowInSeconds?: () => number;
   /** Trusted configuration the public site origin is read from; defaults to process.env. */
   environment?: Record<string, string | undefined>;
+  /** Receives each sign-in failure line; defaults to console.error so it reaches the compute log. */
+  log?: (line: string) => void;
 }
 
 const NO_STORE_HEADERS = { "cache-control": "no-store" };
@@ -91,6 +93,22 @@ function signInFailedResponse(status: number, code: string, message: string): Ne
  * A failed sign-in never leaves the browser on /api/auth/prospectus/callback: it answers 303 to the page the reader started from
  * (or the home page when that is not known) with `sign_in_error=<code>`, which the reader plugin turns into a short message.
  */
+/** Which callback step failed; with the code it tells an operator where a reader's sign-in stopped. */
+type SignInFailureBranch = "pending_cookie" | "provider_error" | "missing_parameters" | "completion" | "unexpected";
+
+/**
+ * One structured line per failed callback: `prospectus_sign_in_failed {"code":...,"branch":...}`. It carries only the
+ * code, the branch, and (for errors from completing the sign-in) the HTTP status, Prospectus error code, its rule text
+ * (`prospectusMessage`, which names the broken rule and carries no personal data) and error name.
+ * Never tokens, authorization codes, state, emails or subjects.
+ */
+function logSignInFailure(
+  options: ProspectusSignInRouteOptions,
+  entry: { code: string; branch: SignInFailureBranch; httpStatus?: number; prospectusError?: string; prospectusMessage?: string; errorName?: string },
+): void {
+  (options.log ?? console.error)(`prospectus_sign_in_failed ${JSON.stringify(entry)}`);
+}
+
 function signInFailedRedirect(request: NextRequest, options: ProspectusSignInRouteOptions, returnPath: string | null, code: string): NextResponse {
   const target = new URL(returnPath ?? "/", siteOriginFor(request, options));
   target.searchParams.set("sign_in_error", /^[a-z0-9_]{1,60}$/.test(code) ? code : "sign_in_failed");
@@ -169,13 +187,16 @@ async function completeCallback(
   options: ProspectusSignInRouteOptions,
   nowInSeconds: number,
 ): Promise<NextResponse> {
-  const failed = (code: string) => signInFailedRedirect(request, options, pendingSignIn?.returnPath ?? null, code);
-  if (!pendingSignIn) return failed("sign_in_expired");
+  const failed = (code: string, branch: SignInFailureBranch, detail: { httpStatus?: number; prospectusError?: string; prospectusMessage?: string; errorName?: string } = {}) => {
+    logSignInFailure(options, { code, branch, ...detail });
+    return signInFailedRedirect(request, options, pendingSignIn?.returnPath ?? null, code);
+  };
+  if (!pendingSignIn) return failed("sign_in_expired", "pending_cookie");
   const searchParams = request.nextUrl.searchParams;
-  if (searchParams.get("error")) return failed("sign_in_declined");
+  if (searchParams.get("error")) return failed("sign_in_declined", "provider_error");
   const authorizationCode = searchParams.get("code");
   const returnedState = searchParams.get("state");
-  if (!authorizationCode || !returnedState) return failed("sign_in_incomplete");
+  if (!authorizationCode || !returnedState) return failed("sign_in_incomplete", "missing_parameters");
   try {
     const signedIn = await completeProspectusGoogleSignIn({
       accounts: runtime.accounts,
@@ -200,9 +221,8 @@ async function completeCallback(
     );
     return response;
   } catch (error) {
-    if (error instanceof ProspectusAccountsError) return failed(error.code);
-    console.error(`Prospectus sign-in failed (${error instanceof Error ? error.name : "error"}).`);
-    return failed("sign_in_failed");
+    if (error instanceof ProspectusAccountsError) return failed(error.code, "completion", { httpStatus: error.status, prospectusError: error.code, prospectusMessage: error.message.slice(0, 300) });
+    return failed("sign_in_failed", "unexpected", { errorName: error instanceof Error ? error.name : "error" });
   }
 }
 

package/lib/prospectus-site-identity.ts

@@ -132,19 +132,28 @@ export function signedProspectusTransport(options: SignedProspectusTransportOpti
 export class ProspectusSiteAccounts {
   constructor(private readonly transport: ProspectusTransport) {}
 
-  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number }> {
+  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number; challengeToken?: string }> {
     return this.transport({ path: "/v1/identities/google/challenge", method: "POST", body: {} }) as Promise<{
       challengeId: string;
       nonce: string;
       expiresAt: number;
+      challengeToken?: string;
     }>;
   }
 
-  resolveGoogleSignIn(challengeId: string, humanAccessToken: string, identityToken: string): Promise<{ person: ProspectusPerson }> {
+  /**
+   * When Prospectus signs its challenges it stores nothing, so the signed `challengeToken` is the only proof the
+   * challenge exists and must be sent back unchanged. Without a token (a service that stores challenges) the ID is sent.
+   */
+  resolveGoogleSignIn(
+    challenge: { challengeId: string; challengeToken?: string },
+    humanAccessToken: string,
+    identityToken: string,
+  ): Promise<{ person: ProspectusPerson }> {
     return this.transport({
       path: "/v1/identities/google/resolve",
       method: "POST",
-      body: { challengeId },
+      body: challenge.challengeToken ? { challengeToken: challenge.challengeToken } : { challengeId: challenge.challengeId },
       humanAccessToken,
       identityToken,
     }) as Promise<{ person: ProspectusPerson }>;
@@ -197,6 +206,8 @@ export interface GoogleOnlyCognitoClient {
 export interface PendingProspectusSignIn {
   challengeId: string;
   nonce: string;
+  /** The signed challenge from Prospectus, present when it signs challenges instead of storing them. */
+  challengeToken?: string;
   state: string;
   codeVerifier: string;
   expiresAt: number;
@@ -242,7 +253,13 @@ export async function beginProspectusGoogleSignIn(
   }).toString();
   return {
     authorizationUrl: authorizationUrl.toString(),
-    pendingSignIn: { challengeId: challenge.challengeId, nonce: challenge.nonce, state, codeVerifier, expiresAt: challenge.expiresAt },
+    pendingSignIn: {
+      challengeId: challenge.challengeId,
+      nonce: challenge.nonce,
+      ...(challenge.challengeToken ? { challengeToken: challenge.challengeToken } : {}),
+      state, codeVerifier,
+      expiresAt: challenge.expiresAt,
+    },
   };
 }
 
@@ -303,7 +320,7 @@ export async function completeProspectusGoogleSignIn(
     expiresInSeconds: Number(tokenBody.expires_in) || 0,
   };
   await (input.verifyCognitoTokens ?? cognitoTokenVerifier(input.cognitoClient))(tokens, input.pendingSignIn.nonce);
-  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn.challengeId, tokens.accessToken, tokens.idToken);
+  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn, tokens.accessToken, tokens.idToken);
   return {
     person,
     accessToken: tokens.accessToken,

package/package.json

@@ -448,7 +448,7 @@
       "optional": true
     }
   },
-  "version": "5.35.0",
+  "version": "5.37.0",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-crypto/sha256-js": "5.2.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.35.0",
+  "version": "5.37.0",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",